Skip to main content
Hosted onboarding
  • Hosted onboarding is documented. Instead of building onboarding with the API, you can link investors to a page Securitize hosts with only the onboarding steps: identity or business verification, the investment profile and the wallet. The investor comes back to your partnerUrl when done. See Hosted onboarding.
PEP answer optional in the compact suitability
  • isPoliticallyExposedPerson is optional in POST /investors/{investorId}/suitability/compact. A compact suitability without it is complete and gets the same verdict. When sent, it is stored and GET /investors/{investorId}/suitability/compact returns it; when not, answers leaves it out. The full suitability still requires it. See The compact suitability.
Tax identifier check for US persons
  • A US person’s taxId is checked against their name and address. For an individual with a US address and taxCountry US, verification also checks that the Social Security number in taxId belongs to the name and residential address sent. Where investors become verified after screening, the status stays processing until the check answers, and a mismatch moves the investor to manual-review. Where they are verified on submission, the status does not change. Sandbox does not run the check. See Statuses.
US state codes in addresses
  • Breaking: address.state is a US state code. On every create and correction of an individual, a company and a key party, address.state takes the 2-letter code of a US state or DC when that address’s countryCode is US, and must be omitted for any other country. A state on an address outside the US, or a US value that is not a state code (New York), answers 400 validation_error on address.state and stores nothing; both were accepted before. null and an empty string read as omitted, and codes are case-insensitive and stored in upper case. See Create the person.
Documents as multipart, files up to 20 MB
  • Both document routes also take multipart/form-data, with files of up to 20 MB each. POST /investors/{investorId}/documents and POST /investors/{investorId}/key-parties/{keyPartyId}/documents accept each file as a part of its own: front, plus back for a two-sided identity document, or file for a company document, with type, documentNumber and expiresAt as text parts. The file’s type is read from its first bytes. The rules and the answers are those of the JSON body, and JSON uploads are unchanged, with their 10 MB limit. A file part over 20 MB answers 413 payload_too_large; a part that does not belong to the document, or an empty one, answers 400 invalid_document. See Two ways to send the files.
  • 415 mime_not_supported on the document routes now reads Content-Type must be application/json or multipart/form-data (received: …).
Document files up to 10 MB
  • Document files can be up to 10 MB each, measured on the file itself before base64 (previously 5 MB). This applies to identity documents and company documents alike. A two-sided document travels with both files at the maximum in one call: the request body limit is now about 31 MB. A file over 10 MB still answers 413 payload_too_large and nothing is stored.
Suitability verdicts and the compact suitability
  • POST /investors/{investorId}/suitability decides an individual’s verdict from the answers. It answers verified, rejected (the investment approach is not aggressive growth, the investor could bear a loss of up to 30% only, or does not accept illiquidity) or processing (a licensed securities professional or someone affiliated with a securities firm, reviewed by Securitize’s compliance team). A verified suitability also approves the investor’s Securitize Markets brokerage account once their status is verified. acceptsIlliquidity: false now rejects an individual’s suitability. An entity’s suitability still reads verified at once. See The verdict.
  • New operations: POST and GET /investors/{investorId}/suitability/compact. A shorter suitability for individuals, the part a Securitize Markets brokerage account for stocks and ‘40 Act funds requires, with a subset of the full suitability’s fields and the same verdicts. An entity answers 422 with details.reason: investor_type_not_supported. See The compact suitability.
  • Both answer 422 business_rule_violation with details.reason suitability_under_review or suitability_not_approved while the verdict is processing or rejected and the full suitability is not complete. Nothing is stored; the suitability webhook announces the next decision.
W-9 certification, tax forms before verification
  • POST /investors/{investorId}/tax-forms/w9 requires certification. The investor certifies the W-9 in your flow on the certification text Securitize publishes, and you send what they agreed to: certifiedAt, signatureName, subjectToBackupWithholding, isUSPerson (true) and certificationTextVersion (w9-sm-2026-10). A W-9 without it, or with an invalid one, answers 400 validation_error. See The certification.
  • A W-9 subject to backup withholding cannot be sent as data: subjectToBackupWithholding: true answers 422 business_rule_violation, with details.reason backup_withholding_not_supported.
  • Tax forms no longer wait for the investor to be verified. POST /investors/{investorId}/tax-forms and POST /investors/{investorId}/tax-forms/w9 accept the form at any point of the verification; neither answers 422 investor_not_verified any more.
OAuth 2.0 authentication
  • Authentication is OAuth 2.0 client credentials. Exchange the client id and secret Securitize issues you for a bearer token at POST https://partners-api.sandbox.securitize.io/oauth2/token, and send it as Authorization: Bearer on every request; it lasts 2 hours. Ask your Securitize contact for client credentials. See Sandbox and authentication.
  • The gateway answers a missing token with 401 invalid_request and an unknown or expired one with 401 invalid_token, in the OAuth shape {"error", "error_description"}. See When the token is wrong.
  • The same token reads your webhooks back at /webhooks/v1/events (Replay and recover).
  • The token request is in the API reference: Get an access token returns a sandbox token to try the other operations with.
Suitability webhooks
  • New webhooks investor.suitability.updated and investor.dlt_test.updated, in sandbox. Securitize POSTs them to your endpoint every time the verificationStatus of an investor’s suitability or DLT test changes, whoever changed it, with your investorId, your externalInvestorId and the new verdict. See Suitability webhooks. An endpoint without an event-type filter starts receiving them: answer 2xx to types you do not handle.
Whitelisting read on chain
  • GET /investors/{investorId}/wallets/whitelist reads the tokens’ on-chain registries. After your own whitelistings, it lists every other token enabled for your account whose registry already holds one of your wallets for the investor, as whitelisted: tokens that share a registry share their whitelistings. See Tokens that share a registry.
  • whitelistedAt is optional: a row is listed without it when you never whitelisted that wallet on a token of the same registry.
  • A whitelisting reads whitelisted as soon as the registry holds the wallet, in the list and in the answer of POST /investors/{investorId}/wallets/whitelist.
W-9 as data
  • New operation: POST /investors/{investorId}/tax-forms/w9 sends the fields of a verified investor’s W-9 as JSON, instead of a signed PDF; Securitize generates the form’s PDF and puts it on file, recorded as sent by you. Only the partner that leads the investor’s verification can send it. You collect the investor’s certification in your own flow. See Send a W-9 as data.
  • A W-9 sent as data does not replace a form on file: new error code 409 tax_form_already_active, with details.activeTaxForm. To correct or replace the form, contact Securitize support.
Read an investor by its investorId
  • GET /investors/{investorId} takes the investorId Securitize returns, like every other path that names an investor. It replaces GET /investors/{externalInvestorId}; your own id in that path answers 404 investor_not_found. To find an investor by your externalInvestorId, filter the list: GET /investors?externalInvestorId=…. The response, include and the access rules are unchanged.
Tax forms
  • New operation: POST /investors/{investorId}/tax-forms sends the tax form a verified investor signed (W-9, W-8BEN or W-8BEN-E), as one PDF of up to 10 MB, so Securitize has it on file for withholding. The body is multipart/form-data: the PDF in the file part, with formType and signatureDate. Only the partner that leads the investor’s verification can send it, and each upload replaces the form on file. See Send a tax form.
  • New error codes: 422 tax_form_type_not_allowed, with details.allowed, and 502 tax_form_registration_failed.
KYC webhooks
  • New webhook investor.kyc.updated, in sandbox. Securitize POSTs it to your endpoint every time the status of one of your investors changes, with your investorId, your externalInvestorId and the new status. See KYC webhooks; your Securitize contact registers the endpoint and hands you its signing secret.
Larger document files
  • Document files can be up to 5 MB each, measured on the file itself before base64 (previously about 1.5 MB). This applies to identity documents and company documents alike. A two-sided document travels with both files at the maximum in one call: the request body limit is now about 16 MB. A file over 5 MB still answers 413 payload_too_large and nothing is stored.
Developer portal
The SecId API documentation moves to this portal: the API reference, the guides for individuals, companies, wallets, whitelisting, suitability and the DLT test, and the material coding agents read.Changes since the integration manual v1.1 (September 2026):
  • An individual’s verification starts with the submit. POST /investors/{investorId}/verification/submit is now a required step for individuals, as for companies. The document that completes the set answers verification.status: awaiting_submission and the investor stays none until you submit. Corrections are accepted until the submit.
  • Creates are repeatable with the same body. The same create sent again answers 201 with the same id; a different body for the same externalInvestorId answers 409. This applies to investors and key parties.
  • The batch create with documents is removed. POST /investors no longer exists; create the investor, then upload its documents one by one.
  • taxId and taxCountry (individuals) and entityIdNumber (companies) are required, and placeholder values are refused.
  • Wallets are identified by their address alone; title is no longer accepted. Registering an address the investor already holds answers 201, and your list shows the wallets you registered.
  • New operations: token whitelisting (/investors/{investorId}/wallets/whitelist), the suitability and the DLT test.
  • A date of birth after today is refused with 400 validation_error, on individuals and person key parties.
  • A document’s content can also be a data URL (data:<mime>;base64,…), as a browser’s FileReader produces it.
  • Error messages are clearer and never name internal systems. Branch on code, as always. A method and path that match no operation answer 404 route_not_found.