Onboard an individual

An individual is verified with the identity data you send and one identity document. Nothing is verified until you submit: the create and the document only prepare the investor.

POST /investors/individual                        create the person        → investorId
POST /investors/{investorId}/documents            their identity document
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, email, taxId) with fresh values of your own: the examples already exist in sandbox.

1. Create the person

curl -X POST "$BASE/investors/individual" -H "Authorization: Bearer $ACCESS_TOKEN" -H "content-type: application/json" -d '{
  "externalInvestorId": "cust-2001",
  "investorType": "individual",
  "email": "ana.sample@test.invalid",
  "firstName": "Test_Jane",
  "lastName": "Sample",
  "dateOfBirth": "1990-04-12",
  "birthCountry": "US",
  "taxId": "571-44-7822",
  "taxCountry": "US",
  "phone": { "code": "1", "number": "5550100001" },
  "address": { "street": "Test Street", "houseNumber": "1", "city": "New York", "state": "NY", "postalCode": "10001", "countryCode": "US" }
}'

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

taxId and taxCountry are required: together they identify the person. Placeholders such as 000000000, 123456789 or TEST are refused, with or without separators (123-45-6789 too).
For a US person, send the Social Security number with the name and residential address it is registered to. Securitize checks that they match, and a mismatch can send the investor to manual-review (see Statuses).
email is unique across all of Securitize, not just your account, and cannot be changed after the create. Use the person’s own address.
address.state is for US addresses only: the 2-letter state code (NY). Leave it out for any other country, even if your form collects a province or region; otherwise the create answers 400 validation_error on address.state.
Branch on the status code. 201 is a new investor. 200 means the person is already registered with Securitize and another party leads the verification: you get limited access.
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. Send the identity document

One identity document per person, with all of its files in the same call:

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

curl -X POST "$BASE/investors/$INVESTOR_ID/documents" -H "Authorization: Bearer $ACCESS_TOKEN" -H "content-type: application/json" -d '{
  "type": "passport",
  "documentNumber": "P1234567",
  "expiresAt": "2032-01-01",
  "files": [ { "side": "front", "mime": "image/png", "content": "'"$(base64 -i passport.png)"'" } ]
}'

Files are JPEG or PNG, base64-encoded (a data: URL prefix is accepted), at most 10 MB each (before base64). The same call also takes multipart/form-data, with the image as a front part of up to 20 MB, which suits large files:

curl -X POST "$BASE/investors/$INVESTOR_ID/documents" -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F type=passport -F documentNumber=P-IND1-0000 -F expiresAt=2032-01-01 -F front=@passport.png

The file is read optically, so it must be a real, legible image: a truncated or corrupt file answers 422 document_rejected and nothing is stored. In sandbox, use the sample passport; see Documents for every file rule. The response tells you where the person stands:

{
  "documents": [ { "id": "6ace7461ab21fd6924a19c09", "type": "passport", "documentNumber": "P1234567", "expiresAt": "2032-01-01", "uploadedAt": "2026-10-13T18:11:45.540Z", "side": "front" } ],
  "verification": { "status": "awaiting_submission", "missing": [] }
}

awaiting_submission means the person is ready and waiting for your submit; nothing else happens on its own. The investor’s status stays none.

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

Corrections

Until you submit, you can correct the person with PUT /investors/individual/{investorId}, also after the document is in. It replaces the whole record: send every field again, with the same email and externalInvestorId.

3. Submit

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

Submitting is the only way verification starts. Do it as soon as the document is in. Without an accepted identity document nothing is sent, and the answer is 422 business_rule_violation with details.investor.reason.code: documents-incomplete. A 200 does not always mean the investor was sent. Read status:

submitted: handed over. Go to step 4.
incomplete: it did not go through this time. Wait a few seconds and submit again.

Submit is safe to repeat: an investor already handed over comes back skipped.

4. 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. Poll until the status leaves processing either way.

After you submit

The person’s data and documents are locked: corrections and uploads answer 409 verification_in_review, and after the verdict 409 verification_already_settled. If Securitize needs anything more about the investor, it tells you. 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 person

2. Send the identity document

Corrections

3. Submit

4. Poll for the verdict

After you submit