Skip to main content
POST
/
v0
/
entities
Create an entity
curl --request POST \
  --url https://api.sandbox.lead.bank/v0/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "type": "individual",
  "individual_details": {
    "first_name": "<string>",
    "last_name": "<string>",
    "identification_details": {
      "type": "us_entity",
      "tax_identification": {
        "type": "ssn",
        "value": "<string>"
      },
      "identification_documents": [
        {
          "type": "drivers_license",
          "identification_number": "<string>",
          "issuing_country": "<string>",
          "client_document_id": "<string>",
          "description": "<string>",
          "expiration_date": "2023-12-25",
          "issuing_state": "<string>"
        }
      ]
    },
    "preferred_first_name": "<string>",
    "middle_name": "<string>",
    "date_of_birth": "2002-02-15",
    "occupation": "<string>",
    "contact_methods": [
      {
        "type": "email",
        "email": "abc@gmail.com"
      }
    ],
    "address_details": {
      "physical_address": {
        "line_1": "123 Main St.",
        "city": "Denver",
        "country": "US",
        "line_2": "Apt 25",
        "postal_code": 80014,
        "state": "CO"
      },
      "mailing_address": {
        "line_1": "123 Main St.",
        "city": "Denver",
        "country": "US",
        "line_2": "Apt 25",
        "postal_code": 80014,
        "state": "CO"
      },
      "other_addresses": [
        {
          "line_1": "123 Main St.",
          "city": "Denver",
          "country": "US",
          "line_2": "Apt 25",
          "postal_code": 80014,
          "state": "CO"
        }
      ]
    },
    "additional_documents": [
      {
        "type": "bank_statement",
        "client_document_id": "<string>",
        "description": "<string>"
      }
    ]
  },
  "client_customer_id": "<string>",
  "intended_roles": "Possible values: authorized_user, authorized_signer, account_holder. In the event more than 1 role is passed in and at least 1 role doesn’t pass validation, the request will not succeed. It will be an all or nothing behavior. For type = business, sole_prop, only account_holder should be provided",
  "risk_score": "low",
  "rfi_details": {
    "result": "requested",
    "requested_at": "2023-11-07T05:31:56Z"
  },
  "ofac_details": {
    "result": "pending",
    "screened_at": "2023-11-07T05:31:56Z"
  },
  "kyc_details": {
    "result": "pending",
    "screened_at": "2023-11-07T05:31:56Z"
  },
  "credit_details": [
    {
      "credit_score": "<string>",
      "credit_report_source": "equifax",
      "credit_pulled_at": "2023-11-07T05:31:56Z"
    }
  ],
  "metadata": {}
}
'
{
  "id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "type": "individual",
  "client_customer_id": "<string>",
  "intended_roles": "Possible values: authorized_user, authorized_signer, account_holder. In the event more than 1 role is passed in and at least 1 role doesn’t pass validation, the request will not succeed. It will be an all or nothing behavior. For type = business, sole_prop, only account_holder should be provided",
  "risk_score": "low",
  "individual_details": {
    "first_name": "<string>",
    "last_name": "<string>",
    "identification_details": {
      "type": "us_entity",
      "tax_identification": {
        "type": "ssn",
        "value": "<string>"
      },
      "identification_documents": [
        {
          "type": "drivers_license",
          "identification_number": "<string>",
          "issuing_country": "<string>",
          "client_document_id": "<string>",
          "description": "<string>",
          "expiration_date": "2023-12-25",
          "issuing_state": "<string>"
        }
      ]
    },
    "preferred_first_name": "<string>",
    "middle_name": "<string>",
    "date_of_birth": "2002-02-15",
    "occupation": "<string>",
    "contact_methods": [
      {
        "type": "email",
        "email": "abc@gmail.com"
      }
    ],
    "address_details": {
      "physical_address": {
        "line_1": "123 Main St.",
        "city": "Denver",
        "country": "US",
        "line_2": "Apt 25",
        "postal_code": 80014,
        "state": "CO"
      },
      "mailing_address": {
        "line_1": "123 Main St.",
        "city": "Denver",
        "country": "US",
        "line_2": "Apt 25",
        "postal_code": 80014,
        "state": "CO"
      },
      "other_addresses": [
        {
          "line_1": "123 Main St.",
          "city": "Denver",
          "country": "US",
          "line_2": "Apt 25",
          "postal_code": 80014,
          "state": "CO"
        }
      ]
    },
    "additional_documents": [
      {
        "type": "bank_statement",
        "client_document_id": "<string>",
        "description": "<string>"
      }
    ]
  },
  "rfi_details": {
    "result": "requested",
    "requested_at": "2023-11-07T05:31:56Z"
  },
  "ofac_details": {
    "result": "pending",
    "screened_at": "2023-11-07T05:31:56Z"
  },
  "kyc_details": {
    "result": "pending",
    "screened_at": "2023-11-07T05:31:56Z"
  },
  "credit_details": [
    {
      "credit_score": "<string>",
      "credit_report_source": "equifax",
      "credit_pulled_at": "2023-11-07T05:31:56Z"
    }
  ],
  "role_details": [
    {
      "name": "authorized_user",
      "status": "active",
      "criteria_details": [
        {
          "failed_checks": [
            "<string>"
          ],
          "entity_id": "<string>"
        }
      ]
    }
  ],
  "metadata": {}
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Idempotency-Key
string
required

Idempotency key

Maximum string length: 255

Body

application/json
​
type
string
default:individual
required

Type of entity = individual.

Pattern: ^individual$
​
individual_details
object
required

Details for the individual entity

​
client_customer_id
string

Client customer ID for the entity object. Limit of 64 characters.

Maximum string length: 64
​
intended_roles
enum<string>[]

The entity's intended role. Lead highly recommends using this field to confirm data requirements for different roles to minimize errors later. In the event more than 1 role is passed in and at least 1 role doesn’t pass validation, the request will not succeed. It will be an all or nothing behavior. Lead currently supports:

  • authorized_user: Individual entity with restricted access to the account, without legal responsibility. Only applies to individual entity.
  • authorized_signer: Individual entity allowed to sign on behalf of the account holder, without legal responsibility. Only applies to individual entity.
  • account_holder: Entity with full control and legal responsibility for the account. Applies to all entity types.
Available options:
authorized_user,
authorized_signer,
account_holder
Example:

"Possible values: authorized_user, authorized_signer, account_holder. In the event more than 1 role is passed in and at least 1 role doesn’t pass validation, the request will not succeed. It will be an all or nothing behavior. For type = business, sole_prop, only account_holder should be provided"

​
risk_score
enum<string>

The entity's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead.

Available options:
low,
medium,
high
​
rfi_details
object
​
ofac_details
object

Details on OFAC on the entity.

​
kyc_details
object

Details on KYC on the entity.

​
credit_details
object[]
​
metadata
object

A set of key-value pairs that can be used to store additional information related to this object.

Response

Entity object created.

​
id
string
required

Unique ID for the Entity object.

​
created_at
string<date-time>
required

Timestamp at which the entity object is created.

​
updated_at
string<date-time>
required

Timestamp at which the entity object was last updated.

​
type
string
default:individual
required

Type of entity = individual.

Pattern: ^individual$
​
client_customer_id
string

Client customer ID for the entity object. Limit of 64 characters.

Maximum string length: 64
​
intended_roles
enum<string>[]

The entity's intended role. Lead highly recommends using this field to confirm data requirements for different roles to minimize errors later. In the event more than 1 role is passed in and at least 1 role doesn’t pass validation, the request will not succeed. It will be an all or nothing behavior. Lead currently supports:

  • authorized_user: Individual entity with restricted access to the account, without legal responsibility. Only applies to individual entity.
  • authorized_signer: Individual entity allowed to sign on behalf of the account holder, without legal responsibility. Only applies to individual entity.
  • account_holder: Entity with full control and legal responsibility for the account. Applies to all entity types.
Available options:
authorized_user,
authorized_signer,
account_holder
Example:

"Possible values: authorized_user, authorized_signer, account_holder. In the event more than 1 role is passed in and at least 1 role doesn’t pass validation, the request will not succeed. It will be an all or nothing behavior. For type = business, sole_prop, only account_holder should be provided"

​
risk_score
enum<string>

The entity's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead.

Available options:
low,
medium,
high
​
individual_details
object

Details for the individual entity

​
rfi_details
object
​
ofac_details
object

Details on OFAC on the entity.

​
kyc_details
object

Details on KYC on the entity.

​
credit_details
object[]
​
role_details
object[]
​
metadata
object

A set of key-value pairs that can be used to store additional information related to this object.