Skip to main content

Onboarding

GET /investors/{id} answers 404, but the create answered 201. Every path that names an investor takes Securitize’s investorId, the one the create returned, not your externalInvestorId. If you only have your own id, find the investorId with GET /investors?externalInvestorId=…. See Identifiers. I uploaded the passport and the investor’s status is still none. Is it stuck? No. Nothing is verified until you submit. Read verification.status on the upload: awaiting_submission means the investor is ready; call POST /investors/{investorId}/verification/submit. See Statuses. A key party’s upload answered awaiting_submission. Should I wait? No: that person is ready. Nothing happens until you submit the entity. The submit answered 200 with status: incomplete. Did it fail? Partly: part of it did not go through. Call submit again; what was already handed over is skipped. The submit answered 422 and the ready key parties read not_attempted. Were they sent? No. The submit is all or nothing. Upload what details says is missing, then submit again. Can I correct a typo after the document upload? Yes, until you submit. After the submit the data is locked; contact Securitize if it must change. Why did PUT clear fields I did not send? PUT replaces the whole record. Always send the complete record. Does a company document start the entity’s verification? No. Company documents are filed for compliance review. Only the submit starts a verification. Can a company be a key party? Yes, as a corporate shareholder through POST …/key-parties/entity. Also declare the people behind it: a company is screened through natural persons. See Onboard a company. The create answered 200 instead of 201. The investor is already registered with Securitize and another party leads the verification. Store the investorId; you have limited access. A create timed out. Can I send it again? Yes, with exactly the same body: you get 201 and the same investorId. See Identifiers.

Documents

Why can I not send a PDF of the passport? Identity documents are read optically and must be JPEG or PNG; a PDF answers 415. PDF is accepted for company documents. I got 502 document_outcome_unknown. Should I send it again? Yes. The document was kept, and sending it again is safe; the extra copy is harmless. See Documents.

Status and verdict

Is manual-review a rejection? No. A Securitize compliance operator is reviewing the investor. Keep it pending and keep polling. See Handling manual-review. Is there a webhook? Yes, in sandbox: investor.kyc.updated is sent every time an investor’s status changes, and investor.suitability.updated / investor.dlt_test.updated every time a suitability or DLT test verdict changes. See KYC webhooks and Suitability webhooks. Keep polling GET /investors/{investorId} as a safety net; see the polling cadence. How do I tell an individual from an entity in a read? investorType is not returned. With include=details, an individual has firstName; an entity has entityName.

Wallets and whitelisting

Whitelisting answers 422 suitability_not_verified. Send the suitability first; for an investor in the EEA, the DLT test must be passed too. details.notVerified names which. A suitability that reads processing or rejected is not verified either. See Suitability and the DLT test. The whitelisting has been processing for a while. Keep polling the list for the token. If it lasts more than a day, contact Securitize with the correlationId. Can I remove a wallet or a whitelisting? Not through the API. Contact Securitize.

Tax forms

My document files are larger than 10 MB. Send the document as multipart/form-data, with each file as a part: up to 20 MB a file, on the same route. As base64 JSON, a file can be at most 10 MB. Above 20 MB, reduce the scan. See Two ways to send the files. Can I send the tax form as base64, like a document? No. A signed tax form is sent as multipart/form-data, with the PDF as a file part; a JSON body there answers 415. See Send a tax form. Can I send a W-9 without a PDF? Yes. If the investor fills in the W-9 in your app, send its fields as JSON to POST /investors/{investorId}/tax-forms/w9, and Securitize generates the PDF. The investor certifies it in your flow first, on the certification text Securitize publishes, and you send that certification with the fields. The W-8BEN and W-8BEN-E are sent as signed PDFs only. See Send a W-9 as data. How do I correct a W-9 I sent as data? Contact Securitize support with its taxFormId. A W-9 sent as data does not replace a form on file: while one is there, the call answers 409 tax_form_already_active. How do I know when a W-8 expires? From the date it was signed: a W-8BEN or W-8BEN-E is valid until December 31 of the third year after the year it was signed. The API does not notify you; send a newly signed form before that date. A W-9 does not expire. Can I read back the tax form I sent? No. The answer is the receipt: keep its taxFormId to quote to Securitize support. A new PDF upload replaces the form on file.

Errors

My 401 has no correlationId. Is that a bug? No. 401 and 403 without a code come from the gateway, before the API: on a 401, get a new token and send the request again; a 403 means your account is not enabled for this API. See Errors.