Create an entity investor

curl --request POST \
  --url https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors/entity \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalInvestorId": "ent-test-0001",
  "investorType": "entity",
  "entityName": "Test_Northwind Holdings LLC",
  "entityType": "llc",
  "incorporationDate": "2015-06-30",
  "entityIdNumber": "39-8873890",
  "email": "kyc.sandbox+ent0001@test.invalid",
  "phone": {
    "code": "1",
    "number": "5550000001"
  },
  "address": {
    "street": "Test Street",
    "houseNumber": "1",
    "city": "Wilmington",
    "state": "DE",
    "countryCode": "US",
    "postalCode": "19801"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    externalInvestorId: 'ent-test-0001',
    investorType: 'entity',
    entityName: 'Test_Northwind Holdings LLC',
    entityType: 'llc',
    incorporationDate: '2015-06-30',
    entityIdNumber: '39-8873890',
    email: 'kyc.sandbox+ent0001@test.invalid',
    phone: {code: '1', number: '5550000001'},
    address: {
      street: 'Test Street',
      houseNumber: '1',
      city: 'Wilmington',
      state: 'DE',
      countryCode: 'US',
      postalCode: '19801'
    }
  })
};

fetch('https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors/entity', 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/entity"

payload = {
    "externalInvestorId": "ent-test-0001",
    "investorType": "entity",
    "entityName": "Test_Northwind Holdings LLC",
    "entityType": "llc",
    "incorporationDate": "2015-06-30",
    "entityIdNumber": "39-8873890",
    "email": "kyc.sandbox+ent0001@test.invalid",
    "phone": {
        "code": "1",
        "number": "5550000001"
    },
    "address": {
        "street": "Test Street",
        "houseNumber": "1",
        "city": "Wilmington",
        "state": "DE",
        "countryCode": "US",
        "postalCode": "19801"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "investorId": "31941ef930d5518999d55bee",
  "externalInvestorId": "ent-test-0001",
  "status": "processing"
}

Entities

Create an entity investor

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

The body carries no documents and no key parties, and nothing here starts a verification. On a 201, status is none and stays none until you submit: a company is screened through its key parties, never on its own, and its own documents do not move it either.

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

201 — the company was created, or this request repeats its create exactly (see below). Next: add its key parties with POST /investors/{investorId}/key-parties/individual (and …/key-parties/entity for corporate shareholders).
200 — { investorId, externalInvestorId, status }: this company is already registered with Securitize and another party leads the verification. Store investorId; status is its current one and may already be processing or verified. You have limited access to it: you can read its status and manage its wallets, token whitelisting, suitability and DLT test; corrections, key parties, 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 entity’s current status, and 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/entity/{investorId} to change data. The entityIdNumber + address.countryCode of an entity you already created, under another externalInvestorId, answers the same 409 with that entity’s investorId.

POST

investors

entity

Create an entity investor

curl --request POST \
  --url https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors/entity \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalInvestorId": "ent-test-0001",
  "investorType": "entity",
  "entityName": "Test_Northwind Holdings LLC",
  "entityType": "llc",
  "incorporationDate": "2015-06-30",
  "entityIdNumber": "39-8873890",
  "email": "kyc.sandbox+ent0001@test.invalid",
  "phone": {
    "code": "1",
    "number": "5550000001"
  },
  "address": {
    "street": "Test Street",
    "houseNumber": "1",
    "city": "Wilmington",
    "state": "DE",
    "countryCode": "US",
    "postalCode": "19801"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    externalInvestorId: 'ent-test-0001',
    investorType: 'entity',
    entityName: 'Test_Northwind Holdings LLC',
    entityType: 'llc',
    incorporationDate: '2015-06-30',
    entityIdNumber: '39-8873890',
    email: 'kyc.sandbox+ent0001@test.invalid',
    phone: {code: '1', number: '5550000001'},
    address: {
      street: 'Test Street',
      houseNumber: '1',
      city: 'Wilmington',
      state: 'DE',
      countryCode: 'US',
      postalCode: '19801'
    }
  })
};

fetch('https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors/entity', 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/entity"

payload = {
    "externalInvestorId": "ent-test-0001",
    "investorType": "entity",
    "entityName": "Test_Northwind Holdings LLC",
    "entityType": "llc",
    "incorporationDate": "2015-06-30",
    "entityIdNumber": "39-8873890",
    "email": "kyc.sandbox+ent0001@test.invalid",
    "phone": {
        "code": "1",
        "number": "5550000001"
    },
    "address": {
        "street": "Test Street",
        "houseNumber": "1",
        "city": "Wilmington",
        "state": "DE",
        "countryCode": "US",
        "postalCode": "19801"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "investorId": "31941ef930d5518999d55bee",
  "externalInvestorId": "ent-test-0001",
  "status": "processing"
}

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 company being onboarded. The same body creates it and, on PUT, replaces it in full: an optional field you omit on PUT is cleared.

externalInvestorId

string

required

Your own id for this company, 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 entity on this route.

Available options:

entity

entityName

string

required

Registered legal name. This is what sanctions and PEP screening run against.

Required string length: 1 - 255

entityIdNumber

string

required

Registration or tax identifier of the company as a legal person. With address.countryCode it identifies the company. 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).

Required string length: 1 - 128

Example:

"39-8873890"

string<email>

required

Contact email of the company. ASCII local part only. Unique across Securitize: an address that belongs to another investor answers 409 email_conflict. Fixed at create: on PUT send the same value.

phone

object

required

Contact phone of the company.

Show child attributes

address

object

required

Registered address. countryCode together with entityIdNumber identifies the company.

Show child attributes

entityType

enum<string>

Legal form of the company.

Available options:

revocable-trust,

irrevocable-trust,

limited-partnership/general-partnership,

joint-account,

non-profit-foundation,

for-profit-foundation,

fund,

llc,

corporation,

other

incorporationDate

string<date>

Date of incorporation, YYYY-MM-DD. Returned as a timestamp.

Example:

"2015-06-30"

Response

The company is already registered with Securitize and another party leads the verification. Store investorId; status is its 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 entity investor

Authorizations

Body

Response