Skip to main content
The API has two kinds of status, and reading the wrong one is the most common integration mistake:
  • the investor’s status: where the verification stands. Read it with GET /investors/{investorId}.
  • verification.status on document uploads: whether that investor or key party has what verification needs. It tells you what to do next; it never changes on its own.

Investor status

When verified arrives depends on your agreement with Securitize. For some partners an investor is verified as soon as the submit completes; for others the status goes through processing until screening answers. Requests and responses are the same either way. An entity with corporate shareholders can stay processing until compliance has reviewed them. A US person’s tax identifier is checked as well. For an individual with a US address and taxCountry US, Securitize also checks that the taxId belongs to the name and residential address you sent. If your investors become verified after screening, the status stays processing until that check answers, and a taxId that does not match moves the investor to manual-review. If they are verified on submission, the check does not change the status. Sandbox does not run this check. Treat any status you do not recognise as “not verified” rather than failing.

Polling for the verdict

A KYC webhook tells you every time the status changes; keep a poller as a safety net. A worker separate from your onboarding flow polls GET /investors/{investorId} without include, which is the lightest call.
  • processing is the expected intermediate state: do not back off on it. Back off on 500.
  • To read many investors in one call, filter GET /investors by several externalInvestorId values: ?externalInvestorId=a&externalInvestorId=b (up to 20 per page).

Handling manual-review

manual-review means screening produced a hit, or a US person’s tax identifier did not match their name and address, and a Securitize compliance operator has to resolve it. It is not a rejection and not an error in your integration.
  • Keep the investor pending in your product. Do not grant access that depends on KYC, and do not tell the investor they were declined.
  • Keep polling at the production cadence; the status changes when the operator decides.
  • Do not send corrections or more documents: the record is locked. If the operator needs more information, Securitize contacts you.
  • Keep the investorId, externalInvestorId and the submit’s correlationId where your operations team can find them, to reference the case with Securitize.

verification.status on document uploads

missing names what is still owed, for example ["IDENTITY"] or a list of company document types. Ready never means started: verification starts only with your submit. An upload after the investor was submitted, when Securitize asked for more information, reads submitted.

The submit response

POST /investors/{investorId}/verification/submit answers 200 with status: submitted when everything was handed over, or status: incomplete when part of it did not go through; then call it again. Each subject (the investor, and an entity’s key parties) reports a result: submitted, skipped (already handed over, not sent again), failed or not_attempted. Submitting again is always safe. Details in the API reference.

When data locks

email and externalInvestorId never change after the create. If one must change, contact Securitize.

Other statuses