Create an individual investor

curl --request POST \
  --url https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors/individual \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalInvestorId": "ind-test-0001",
  "investorType": "individual",
  "email": "kyc.sandbox+ind0001@test.invalid",
  "firstName": "Test_Jane",
  "middleName": "Sample",
  "lastName": "Investor",
  "dateOfBirth": "1990-04-12",
  "birthCountry": "US",
  "taxId": "123-45-6780",
  "taxCountry": "US",
  "phone": {
    "code": "1",
    "number": "5550100001"
  },
  "address": {
    "street": "Test Street",
    "houseNumber": "1",
    "city": "New York",
    "state": "NY",
    "countryCode": "US",
    "postalCode": "10001"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    externalInvestorId: 'ind-test-0001',
    investorType: 'individual',
    email: 'kyc.sandbox+ind0001@test.invalid',
    firstName: 'Test_Jane',
    middleName: 'Sample',
    lastName: 'Investor',
    dateOfBirth: '1990-04-12',
    birthCountry: 'US',
    taxId: '123-45-6780',
    taxCountry: 'US',
    phone: {code: '1', number: '5550100001'},
    address: {
      street: 'Test Street',
      houseNumber: '1',
      city: 'New York',
      state: 'NY',
      countryCode: 'US',
      postalCode: '10001'
    }
  })
};

fetch('https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors/individual', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors/individual"

payload = {
    "externalInvestorId": "ind-test-0001",
    "investorType": "individual",
    "email": "kyc.sandbox+ind0001@test.invalid",
    "firstName": "Test_Jane",
    "middleName": "Sample",
    "lastName": "Investor",
    "dateOfBirth": "1990-04-12",
    "birthCountry": "US",
    "taxId": "123-45-6780",
    "taxCountry": "US",
    "phone": {
        "code": "1",
        "number": "5550100001"
    },
    "address": {
        "street": "Test Street",
        "houseNumber": "1",
        "city": "New York",
        "state": "NY",
        "countryCode": "US",
        "postalCode": "10001"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "investorId": "6ace6a01b2d94ceccd1999e4",
  "externalInvestorId": "ind-test-0001",
  "status": "verified"
}

Individuals

Create an individual investor

Creates the person you are onboarding. Call it first; every other operation on the investor takes the investorId it returns, so store it against your own record.

The body carries no documents, and nothing here starts a verification. On a 201, status is none and stays none until you submit the investor with POST /investors/{investorId}/verification/submit. Next: upload the person’s identity document with POST /investors/{investorId}/documents.

Branch on the status code, not only on the body:

201 — the investor was created, or this request repeats its create exactly (see below). Next: upload the identity document.
200 — { investorId, externalInvestorId, status }: this person is already registered with Securitize and another party leads the verification. Store investorId; status is the current one and may already be verified. You have limited access: you can read its status and manage its wallets, token whitelisting, suitability and DLT test; corrections, documents, submit and include answer 409 investor_not_owned.

Repeatable with the same body. Sending the same create again — the same externalInvestorId, email and data as last stored (by the create or a later correction) — answers 201 with the same investorId and the investor’s current status. It also finishes a registration that a 502 left incomplete. A different body for the same externalInvestorId answers 409 external_investor_id_conflict with the investorId in details: use PUT /investors/individual/{investorId} to change data.

taxId with taxCountry identifies the person: a create carrying the tax identity of an investor you already created, under another externalInvestorId, answers 409 external_investor_id_conflict with that investor’s investorId. Submit as soon as the documents are complete.

POST

investors

individual

Create an individual investor

curl --request POST \
  --url https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors/individual \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalInvestorId": "ind-test-0001",
  "investorType": "individual",
  "email": "kyc.sandbox+ind0001@test.invalid",
  "firstName": "Test_Jane",
  "middleName": "Sample",
  "lastName": "Investor",
  "dateOfBirth": "1990-04-12",
  "birthCountry": "US",
  "taxId": "123-45-6780",
  "taxCountry": "US",
  "phone": {
    "code": "1",
    "number": "5550100001"
  },
  "address": {
    "street": "Test Street",
    "houseNumber": "1",
    "city": "New York",
    "state": "NY",
    "countryCode": "US",
    "postalCode": "10001"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    externalInvestorId: 'ind-test-0001',
    investorType: 'individual',
    email: 'kyc.sandbox+ind0001@test.invalid',
    firstName: 'Test_Jane',
    middleName: 'Sample',
    lastName: 'Investor',
    dateOfBirth: '1990-04-12',
    birthCountry: 'US',
    taxId: '123-45-6780',
    taxCountry: 'US',
    phone: {code: '1', number: '5550100001'},
    address: {
      street: 'Test Street',
      houseNumber: '1',
      city: 'New York',
      state: 'NY',
      countryCode: 'US',
      postalCode: '10001'
    }
  })
};

fetch('https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors/individual', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors/individual"

payload = {
    "externalInvestorId": "ind-test-0001",
    "investorType": "individual",
    "email": "kyc.sandbox+ind0001@test.invalid",
    "firstName": "Test_Jane",
    "middleName": "Sample",
    "lastName": "Investor",
    "dateOfBirth": "1990-04-12",
    "birthCountry": "US",
    "taxId": "123-45-6780",
    "taxCountry": "US",
    "phone": {
        "code": "1",
        "number": "5550100001"
    },
    "address": {
        "street": "Test Street",
        "houseNumber": "1",
        "city": "New York",
        "state": "NY",
        "countryCode": "US",
        "postalCode": "10001"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "investorId": "6ace6a01b2d94ceccd1999e4",
  "externalInvestorId": "ind-test-0001",
  "status": "verified"
}

Authorizations

Authorization

string

header

required

OAuth 2.0 client credentials. Exchange the client id and secret Securitize issued you for a bearer token at the token URL (the host root, not under the base URL), with grant_type=client_credentials; the token lasts 2 hours and goes in the Authorization: Bearer header of every request. No scope is needed. The token identifies your partner account, so you never send a partner id, and every record you create is scoped to you.

Body

application/json

The person being onboarded. The same body creates the investor and, on PUT, replaces it in full: an optional field you omit on PUT is cleared.

externalInvestorId

string

required

Your own id for this person, unique within your partner account. Fixed at create: on PUT send the same value.

Pattern: ^[A-Za-z0-9._-]{1,128}$

Example:

"ent-test-0001"

investorType

enum<string>

required

Always individual on this route.

Available options:

individual

string<email>

required

The person's email. ASCII local part only; stored in lower case. Unique across Securitize: an address that belongs to another investor answers 409 email_conflict. Fixed at create: on PUT send the same value.

firstName

string

required

First name. This is what sanctions and PEP screening run against.

Required string length: 1 - 128

lastName

string

required

Last name.

Required string length: 1 - 128

dateOfBirth

string<date>

required

Date of birth, YYYY-MM-DD, not later than today (UTC); a later date answers 400 validation_error. Returned as a timestamp.

Example:

"2015-06-30"

birthCountry

string

required

Country of birth.

Pattern: ^[A-Za-z]{2}$

Example:

"US"

taxId

string

required

Tax identifier. With taxCountry it identifies the person. Stored trimmed and upper-cased. Placeholder values (000000000, 123456789, TEST, N/A, one repeated character, fewer than 4 characters) are refused with 400 validation_error, with or without separators (spaces, dots, dashes, slashes). For a US person (US address and taxCountry US) it is the Social Security number, and verification checks that it matches the name and residential address; a mismatch can send the investor to manual-review. Sandbox does not run that check.

Required string length: 1 - 50

Example:

"123-45-6780"

taxCountry

string

required

Country that issued the tax identifier.

Pattern: ^[A-Za-z]{2}$

Example:

"US"

phone

object

required

The person's phone.

Show child attributes

address

object

required

Residential address. Its country, with taxCountry, feeds the risk level.

Show child attributes

middleName

string

Middle name.

Maximum string length: 128

gender

enum<string>

Gender.

Available options:

male,

female

Response

The person is already registered with Securitize and another party leads the verification. Store investorId; status is the current one. You can read its status and manage its wallets, token whitelisting, suitability and DLT test; every other operation on it answers 409 investor_not_owned.

An investor already registered with Securitize whose verification another party leads. You have limited access: you can read its status and manage its wallets, token whitelisting, suitability and DLT test; every other operation on it answers 409 investor_not_owned.

investorId

string

required

Securitize's id for this investor in your partner account. Store it.

Minimum string length: 1

Example:

"6aca84e5dc49fe8369dd1da4"

externalInvestorId

string

required

Your own id, as sent at create.

Pattern: ^[A-Za-z0-9._-]{1,128}$

Example:

"ent-test-0001"

status

enum<string>

required

The investor's verification state.

none — created, nothing under review. An investor stays here until you submit it.
processing — under review.
verified — verified.
manual-review — a Securitize operator is reviewing it. Not a rejection.
updates-required — Securitize needs updated information; contact Securitize support.
expired — the verification lapsed; contact Securitize support.
rejected — final.

When status becomes verified — at submit, or after Securitize's screening and compliance review — depends on your agreement with Securitize. Treat any value you do not recognise as "not verified" rather than failing.

Available options:

none,

processing,

verified,

manual-review,

updates-required,

expired,

rejected

Get started

Guides

Concepts

Help

API reference

Create an individual investor

Authorizations

Body

Response