Onboard a company

A company (an entity) is verified through its key parties: the people who own or control it, and optionally the companies that hold shares in it. You declare them, send their documents, and then submit. Nothing is verified until you submit.

POST /investors/entity                                          create the company        → investorId
POST /investors/{investorId}/key-parties/individual             each person behind it     → keyPartyId
   POST /investors/{investorId}/key-parties/entity                 each corporate shareholder (optional)
POST /investors/{investorId}/key-parties/{keyPartyId}/documents  their documents
POST /investors/{investorId}/verification/submit                start verification
GET  /investors/{investorId}                                    poll for the verdict

The examples use $BASE for https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance and $ACCESS_TOKEN for a bearer token (get one). Replace the identifiers in them (externalInvestorId, entityIdNumber, email) with fresh values of your own: the examples already exist in sandbox.

1. Create the company

curl -X POST "$BASE/investors/entity" -H "Authorization: Bearer $ACCESS_TOKEN" -H "content-type: application/json" -d '{
  "externalInvestorId": "acme-1001",
  "investorType": "entity",
  "entityName": "Northwind Test Holdings LLC",
  "entityType": "llc",
  "entityIdNumber": "47-3829104",
  "email": "ops.northwind@test.invalid",
  "phone": { "code": "1", "number": "5550000101" },
  "address": { "street": "1 Test Street", "city": "Wilmington", "state": "DE", "postalCode": "19801", "countryCode": "US" }
}'

Store the investorId from the response. Things that commonly go wrong:

entityIdNumber is required, together with address.countryCode: they identify the company. Placeholders such as 000000000 or N/A are refused, with or without separators.
email is unique across all of Securitize, not just your account, and cannot be changed after the create. Use the company’s own contact address, not a shared one.
address.state is for US addresses only, for the company and for each key party, judged on each address’s own countryCode: the 2-letter state code (DE). Leave it out for any other country; otherwise the call answers 400 validation_error on address.state.
Branch on the status code. 201 is a new company. 200 means the company is already registered with Securitize and another party leads the verification: you get limited access and cannot add key parties or documents.
Repeating the same create is safe. If a create timed out or answered 502, send exactly the same body again: you get 201 with the same investorId. The same externalInvestorId with different data answers 409 external_investor_id_conflict, with the investorId in details.

2. Declare the people behind it

Add every person who owns or controls the company:

curl -X POST "$BASE/investors/$INVESTOR_ID/key-parties/individual" -H "Authorization: Bearer $ACCESS_TOKEN" -H "content-type: application/json" -d '{
  "externalKeyPartyId": "acme-1001-owner-1",
  "isBeneficialOwner": true,
  "uboOwning": "25+",
  "firstName": "Jane",
  "lastName": "Doe",
  "dateOfBirth": "1984-02-11",
  "birthCountry": "US",
  "address": { "street": "11 Test Street", "city": "Wilmington", "state": "DE", "postalCode": "19801", "countryCode": "US" }
}'

Declare at least one person as a beneficial owner (isBeneficialOwner: true). If every person is a plain shareholder, the submit answers 200 with status: incomplete and the company failed, the people already sent are locked, and the company’s status can read processing until you add a beneficial owner and submit again.

Corporate shareholders go to POST …/key-parties/entity. They are optional, but they never replace people: a company whose key parties are all companies cannot be submitted.

3. Send their documents

Each person needs one identity document:

`type`	Files
`passport`	1 file, `side: "front"`
`driving-licence`, `national-identity-card`, `residence-permit`	2 files, `front` and `back`

Identity files are JPEG or PNG. Each file can be at most 10 MB as base64 JSON, or 20 MB as multipart/form-data (front and back parts; see Two ways to send the files); a larger one is refused with 413. The file must be a real, legible image: it is read optically, so a truncated or corrupt file answers 422 document_rejected. Each corporate shareholder needs the company documents its entityType requires (one file per call, PDF allowed):

Corporate shareholder `entityType`	Documents required
`corporation`, `other`	`shareholders-list-25-percent-ubo-control`
`llc`	`members-and-authorised-signers-list`, `shareholders-list-25-percent-ubo-control`
`limited-partnership/general-partnership`	`partnership-agreement`, `register-of-partners`, `list-of-officers-and-directors`, `org-chart`
`revocable-trust`, `irrevocable-trust`	`trust-agreement`
`fund`	`offering-agreement`
`for-profit-foundation`	`certificate-of-registration`, `constitutional-document`, `shareholders-list-25-percent-ubo-control`
`non-profit-foundation`	none

GET /investors/{investorId}/key-parties shows where every key party stands. A person reads awaiting_submission once its document is in. A corporate shareholder lists what it still lacks in verification.missing and reads complete when nothing is missing.

Each upload stores a new document. If an upload answers 502 document_outcome_unknown, sending it again is safe; the extra copy is harmless.

The company’s own documents (POST /investors/{investorId}/documents) are optional. Securitize compliance can review them, but they never start or block verification.

4. Submit

curl -X POST "$BASE/investors/$INVESTOR_ID/verification/submit" -H "Authorization: Bearer $ACCESS_TOKEN"

Submitting tells Securitize the set of key parties is complete. It is all-or-nothing: if any key party is missing documents, nothing is sent and the answer is 422 business_rule_violation, with details.keyParties naming who is short. A 200 does not always mean everything was sent. Read status:

submitted: everything was handed over. Go to step 5.
incomplete: part of it did not go through. Wait a few seconds and submit again; only what is outstanding is sent.

Submit is safe to repeat. Anything already under review comes back skipped.

5. Poll for the verdict

curl "$BASE/investors/$INVESTOR_ID" -H "Authorization: Bearer $ACCESS_TOKEN"

Poll with the investorId until the status settles: every 30 seconds for the first few minutes, then every few minutes. A KYC webhook tells you when the status changes. What each status means, the cadence for production and how to handle manual-review are in Statuses. When verified arrives depends on your agreement with Securitize: on submit, or after screening. An entity with corporate shareholders may stay processing until compliance has reviewed them.

After you submit

Once the company or one of its people is under review, their details and documents are locked: corrections and uploads answer 409 verification_in_review, and after the verdict 409 verification_already_settled. Submitting again is always safe; it only re-sends what is outstanding. If Securitize needs anything more, it tells you. Do not add key parties after you submit: they are accepted, but not verified. If the owners of a verified company change, contact Securitize. If you lose an id along the way, see Identifiers. For every error and what to do about it, see Errors.

Get started

Guides

Concepts

Help

API reference

1. Create the company

2. Declare the people behind it

3. Send their documents

4. Submit

5. Poll for the verdict

After you submit