The Entity Object

An entity is one object with five shapes, depending on its type. You create three of them: individual, business, and sole_prop. Lead sets up the other two, lead and partner, and you read them.

{
  "id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d",
  "type": "individual",
  "intended_eligibility": ["account_holder"],
  "risk_score": "low",
  "individual_details": {
    "first_name": "Amanda",
    "last_name": "Reyes",
    "date_of_birth": "1992-02-15",
    "contact_methods": [
      { "type": "email", "email": "amanda@example.com" }
    ],
    "address_details": {
      "physical_address": {
        "line_1": "123 Main St.",
        "line_2": "Apt 25",
        "city": "Denver",
        "state": "CO",
        "postal_code": "80014",
        "country": "US"
      }
    },
    "identification_details": {
      "type": "us_entity",
      "tax_identification": { "type": "ssn", "value": "987654321" }
    },
    "additional_documents": [
      { "file_id": "file_7RwQ2mK9pL4xT1vN8jS5" }
    ]
  },
  "kyc_details": { "result": "passed", "screened_at": "2026-06-11T14:20:00Z" },
  "ofac_details": { "result": "passed", "screened_at": "2026-06-11T14:20:00Z" },
  "eligibility": {
    "account_holder": { "status": "eligible", "failed_checks": [] },
    "minor_account_holder": {
      "status": "ineligible",
      "failed_checks": [
        {
          "check": "CheckDateOfBirthAboveMaximum",
          "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d",
          "reason": "The entity exceeds the maximum age for minor_account_holder."
        }
      ]
    },
    "authorized_signer": { "status": "eligible", "failed_checks": [] },
    "authorized_user": { "status": "eligible", "failed_checks": [] }
  },
  "metadata": {},
  "created_at": "2026-06-11T14:22:05Z",
  "updated_at": "2026-06-11T14:22:05Z"
}

Common individual, business, and `sole_prop` fields

Field	Type	Description
`id`	string	Unique ID, prefixed `entity_`. Lead generates it on create.
`type`	enum	`individual`, `business`, or `sole_prop` on requests. Determines which details object is required.
`client_customer_id`	string	Response only. Your customer ID, on entities you created on v0 or through Entity files. Lead does not return it on entities created on v2.
`intended_eligibility`	array	Optional. The relationship types you intend this entity to hold. When you send it, Lead checks in real time that the entity has the data each listed type needs, and rejects the request with `422 parameters_invalid` if it does not. See Eligibility.
`eligibility`	object	Response only. Whether the entity’s current data qualifies it for each relationship type, with the failing checks. See The eligibility block.
`risk_score`	enum	`low`, `medium`, or `high`. Your risk score, per the mapping you gave Lead. Required for `account_holder` and `minor_account_holder`.
`kyc_details`	object	`{ result, screened_at }`. `result` is `pending`, `passed`, or `failed`, and `screened_at` must be in the past. Your attestation of the outcome from the Know Your Customer (KYC) or Know Your Business (KYB) process you ran on the entity.
`ofac_details`	object	`{ result, screened_at }`. `result` is `pending`, `passed`, or `failed`. `screened_at` must be in the past. Your attestation of the Office of Foreign Assets Control (OFAC) screening you ran on the entity.
`rfi_details`	object	`{ result, requested_at }`. `result` is `requested` or `completed`. Leave it out if you have not sent the customer a request for information.
`credit_details`	array	Credit bureau data. `credit_report_source` (`equifax`, `experian`, or `transunion`) and `credit_pulled_at` are required, plus exactly one of `credit_score` (300 to 850) or `credit_report_non_score_value` (`unestablished` or `frozen`). This is a living record you update over time.
`metadata`	object	Key-value pairs for your own use.
`created_at`, `updated_at`	timestamp	RFC 3339, UTC.

`individual_details`

Required when type is individual. Within it, first_name, last_name, and identification_details are required. identification_details must always be present, but only its type is required. Every other field is optional to create the entity and becomes required only for the relationship types that need it. See Data requirements.

Field	Notes
`first_name`, `last_name`	Legal name. Required. Send names as your customer gave them, including non-Latin characters.
`middle_name`, `preferred_first_name`	Optional.
`date_of_birth`	`YYYY-MM-DD`. `account_holder` and `authorized_signer` require age 18 or older. `minor_account_holder` requires 16 or 17.
`occupation`	Optional.
`contact_methods`	Array of `{ type: email, email }` or `{ type: phone_number, phone_number }`. Optional. Phone numbers use E.123 format, with a +, the country code, and spacing. Lead checks only the first entry for eligibility, so put the contact method you want checked first.
`address_details`	`physical_address`, `mailing_address`, and `other_addresses[]`. Optional.
`identification_details`	Required. Only its `type` is required on create.
`additional_documents`	Optional supporting documents.

`business_details`

Required when type is business or sole_prop. Within it, name (at least two characters), identification_details, and address_details are required.

Field	Notes
`type`	`corporation`, `partnership`, `sole_prop`, `llc`, `trust`, `cooperative`, or `other`. A `business` entity cannot use `sole_prop`. A `sole_prop` entity must.
`name`, `doing_business_as`	The legal name, and the name the business operates under if different.
`industry`	One or more North American Industry Classification System (NAICS) codes, two to six digits, from the 2022 reference files.
`gross_annual_revenue`, `currency_code`	Revenue for the prior fiscal year, with an ISO 4217 currency code.
`website`	Must start with `http://` or `https://`.
`contact_methods`, `address_details`, `identification_details`, `additional_documents`	Same rules as for individuals. Business identification document types differ. See Documents.

Linked entities

Businesses and sole proprietorships need information about the people behind them. Each of those people is their own individual entity, linked to the business by entity_id. To create a business or sole_prop entity, first create an individual entity for each beneficial owner, control person, or sole proprietor. Then create the business or sole_prop entity and reference their entity_id values.

Object	On	Required fields	Notes
`beneficial_owners[]`	`business`	`entity_id`	Optional `ownership_percentage` (0 to 100, up to two decimal places) and `relationship_established_at`. Beneficial owners’ percentages cannot add up to more than 100. Who to list: Beneficial Ownership Requirements.
`control_persons[]`	`business`	`entity_id`, `title`	At least one is required for `account_holder`.
`sole_proprietor`	`sole_prop` (required)	`entity_id`	The individual behind the sole proprietorship.

Each linked individual must meet the data requirements for authorized_signer, even if they will never sign. If one does not, the business or sole_prop is ineligible for account_holder, and its failed_checks point at that individual’s entity_id.

Identification for US and non-US entities

Every entity you create needs identification_details with a type: us_entity if the entity has a US tax ID, non_us_entity if it does not. type is the only field required to create the entity. What else you provide depends on the relationship types the entity will hold.

Relationship type or link	`us_entity`	`non_us_entity`
`authorized_user` only	`type`. `tax_identification` is optional.	`type`. `identification_documents` is optional.
`authorized_signer`, `account_holder`, `minor_account_holder`, or linked as a beneficial owner, control person, or sole proprietor	`type` and `tax_identification`	`type` and at least one `identification_documents[]` entry

us_entity
- tax_identification has a type (ssn, itin, or ein) and a 9-digit value. Send the whole object or leave it out. A type without a valid value is rejected.
- Individuals use ssn or itin. Businesses use ein. Trusts and LLCs can also use ssn or itin. Sole proprietorships can use any of the three.
- A Social Security number (SSN) cannot start with 9. Numbers starting with 9 are Individual Taxpayer Identification Numbers (ITINs), so send them as itin.
- A business cannot switch between us_entity and non_us_entity after creation. If you have not collected a US person’s tax ID yet, send us_entity without tax_identification.
non_us_entity
- Needs at least one identification_documents[] entry for every relationship type except authorized_user.

Missing identification does not block a create unless you list a relationship type that needs it in intended_eligibility. For example, you create a US individual with identification_details.type us_entity, no tax_identification, and no intended_eligibility. The create succeeds, and eligibility shows account_holder and authorized_signer as ineligible because the government ID check fails. If the same request sends intended_eligibility: ["account_holder"], it returns 422 parameters_invalid instead, and Lead does not create the entity. When you collect the SSN, send a PATCH with tax_identification and a kyc_details with result passed and a later screened_at. Lead recomputes eligibility on the response, and the government ID check no longer fails. If the rest of the entity’s data meets the requirements, account_holder and authorized_signer now show as eligible, and you can add the entity to a user account in those roles. To make the PATCH fail unless the entity qualifies, include intended_eligibility: ["account_holder"] in it.

Send only the entity’s own tax ID. Lead records whatever SSN or ITIN you send as that individual’s own, so do not send a parent’s or guardian’s. For a teen authorized_user without their own SSN, leave tax_identification out.

Documents

Entities carry two arrays of documents: identification_documents[] for government-issued ID, and additional_documents[] for supporting documents. Each entry gives its document type in one of two ways. If you have the document as a file, upload it with the Files API, declare its type there, and send its file_id. Lead takes the type from the file and checks that the file exists and belongs to your program. If you do not have a file, send type on the entry instead. Send file_id or type, not both. A request with both, or neither, returns 422 parameters_invalid. When an entry has a file_id, the entity does not return its type. Retrieve it with GET /v2/files/{id}. identification_documents[], inside identification_details, holds government-verified identification.

Field	Required	Notes
`file_id`	One of `file_id` or `type`	A `file_` ID from the Files API. The file’s type must be one the entity type accepts. Accepted types: `individual`: `drivers_license`, `state_or_provincial_id`, `passport`, `permanent_residency_id`, `military_id`, `national_id`, `matriculate_id` `business`: `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange` `sole_prop`: `tax_certificate`, `tax_returns`, `name_certificate`, `drivers_license`, `state_or_provincial_id`, `passport`, `permanent_residency_id`, `military_id`, `national_id`, `matriculate_id`
`type`	One of `file_id` or `type`	The document type, when you do not link a file.
`identification_number`	Yes	The number on the document.
`issuing_country`	Yes	ISO 3166-1 alpha-2.
`issuing_state`	No	When `issuing_country` is `US`, a valid two-letter USPS state code.
`expiration_date`	No	`YYYY-MM-DD`. Cannot be in the past when you create the entity.

additional_documents[], on individual_details or business_details, holds supporting documents. Each entry takes file_id or type, the same as identification documents. The type must be bank_statement, utility_bills, proof_of_address, investigation_report, financial_statement, public_records, adverse_media, or id_selfie. Things to know when you link files:

Link a file when you have one. Upload it with POST /v2/files, declaring its type, then send the returned file_id. You can create an entity before its files exist and add them later with a PATCH.
Each file appears at most once on an entity, and each file has one type. If one document serves two types, like a utility bill that is also proof of address, upload it once for each type. You can link several files of the same type, like an expired and a current passport.
A supplied array replaces the whole array. To add one document, send every existing entry plus the new one. Lead re-checks every file_id in the array.

Address rules

Put the full street address, with the number and street name, in line_1. It must be at least four characters. Use line_2 only for unit details like an apartment, suite, floor, or care-of, and leave it blank otherwise. city and country (ISO 3166-1 alpha-2) are required. US addresses also need a valid USPS state code and a postal_code written as 12345, 12345-6789, or 12345 6789. A physical address cannot be a P.O. box. Businesses and sole proprietorships need a physical address. Do not use a registered-agent address or an address in a prohibited country as a physical address.

Lead and partner entities

Lead provisions a lead entity and one or more partner entities for your program during onboarding. They hold your program’s core accounts. You can read them, but a POST with either type returns 422 parameters_invalid and a PATCH to one returns 422 operation_invalid. The two types have the same shape.

Field	Type	Description
`id`	string	Unique ID, prefixed `entity_`.
`type`	enum	`lead` or `partner`.
`business_details.name`	string	Legal name.
`business_details.doing_business_as`	string or null	The name the business operates under. Lead requires it on new `lead` and `partner` entities, so `null` appears only on older ones.
`business_details.address_details.physical_address`	object	Physical address.
`eligibility`	object	All four relationship types. `account_holder` is always `eligible`. The other three are always `ineligible`, because only individuals can hold them.
`metadata`	object	Key-value pairs.
`created_at`, `updated_at`	timestamp	RFC 3339, UTC.

These entities carry no KYC, OFAC, risk score, identification, documents, or linked entities.

{
  "id": "entity_3XkTBcRw5nYs1LvKqM7hZjDp0Ug",
  "type": "partner",
  "business_details": {
    "name": "Example Fintech Inc.",
    "doing_business_as": "Example",
    "address_details": {
      "physical_address": {
        "line_1": "100 Example St",
        "city": "New York",
        "state": "NY",
        "postal_code": "10006",
        "country": "US"
      }
    }
  },
  "eligibility": {
    "account_holder": { "status": "eligible", "failed_checks": [] },
    "minor_account_holder": { "status": "ineligible", "failed_checks": [ { "check": "…", "entity_id": "entity_3XkTBcRw5nYs1LvKqM7hZjDp0Ug", "reason": "Only individual entities can hold this relationship type." } ] },
    "authorized_signer": { "status": "ineligible", "failed_checks": [ { "check": "…", "entity_id": "entity_3XkTBcRw5nYs1LvKqM7hZjDp0Ug", "reason": "Only individual entities can hold this relationship type." } ] },
    "authorized_user": { "status": "ineligible", "failed_checks": [ { "check": "…", "entity_id": "entity_3XkTBcRw5nYs1LvKqM7hZjDp0Ug", "reason": "Only individual entities can hold this relationship type." } ] }
  },
  "metadata": {},
  "created_at": "2026-08-10T00:00:00Z",
  "updated_at": "2026-08-10T00:00:00Z"
}

The eligibility block

eligibility has one key for each relationship type: account_holder, minor_account_holder, authorized_signer, and authorized_user. All four are always present. Each has a status of eligible or ineligible and a failed_checks array. Each failed check names the check, the entity_id whose data failed, and a human-readable reason. Lead computes eligibility from current data on every read. Eligibility explains how to read and fix each check.

Create and update

POST /v2/entities and PATCH /v2/entities/{id} take the same fields as the object, and both require an Idempotency-Key header of up to 255 characters. A request without one returns 400 idempotency_key_missing. See Idempotency. A request that breaks a field rule on this page returns 422 parameters_invalid naming the field. PATCH changes only the fields you send:

Fields you leave out of an object, like physical_address, keep their stored values.
To add an entry to an array like additional_documents or contact_methods, send the existing entries plus the new one.
type is required and must match the existing entity.
Lead checks the updated entity against intended_eligibility, either the list you send or the one saved from an earlier request. Send [] to clear the saved list.
Identity changes need a fresh KYC attestation:
- For individuals: first_name, last_name, date_of_birth, and tax_identification.
- For businesses and sole proprietorships: business_details.name, business_details.type, and tax_identification.
- For identification documents: a change to type, identification_number, issuing_country, issuing_state, or expiration_date. Adding or swapping a file_id counts only when it changes the document’s type.
- If you’ve sent kyc_details before, include kyc_details with a later screened_at in the same request.

Coming from the v0 Entity API

Entities keep their entity_id across versions. An entity you created on v0 is readable and updatable on v2. v0 stays live until its sunset date, with sandbox time before you have to move. Most fields carry over unchanged. These are the ones that differ:

v0 Entity API	Entity v2	What changed
`type`: `individual`, `business`, `sole_prop`	`type`: adds `lead` and `partner` in responses	New read-only types for Lead and your company.
`client_customer_id` on requests	None	Ignored if sent on v2. Still returned on entities created on v0 or through files.
`intended_roles`	`intended_eligibility`	Renamed. Same values, the same all-or-nothing check, and the same storage: Lead keeps the list and checks every later `PATCH` against it.
`role_details[]`	`eligibility`	An object keyed by relationship type instead of an array. All four keys are always present.
`role_details[].name`	The key, like `eligibility.account_holder`	Read the key directly instead of searching the array.
`role_details[].status`: `active` or `inactive`	`eligibility.<type>.status`: `eligible` or `ineligible`	Renamed values.
`role_details[].criteria_details[].failed_checks[]`	`eligibility.<type>.failed_checks[].check`	One entry per failing check. The `criteria_details` wrapper is gone.
`role_details[].criteria_details[].entity_id`	`eligibility.<type>.failed_checks[].entity_id`	Moved onto each failing check.
None	`eligibility.<type>.failed_checks[].reason`	New. A human-readable explanation and fix.
PascalCase check codes, like `CheckKYCStatus`	The same check names	Unchanged. v2 adds a check for relationship types only individuals can hold.
`identification_documents[].client_document_id`, `additional_documents[].client_document_id`	`file_id` on the same entries	A Files API ID that Lead checks, in place of an SFTP filename.
`identification_documents[].type`, `additional_documents[].type`	`file_id` or `type` on each entry	When you link a file, Lead takes the type from the file. Without a file, send `type` on the entry.
None	`legacy_identification_documents[]`, `legacy_additional_documents[]`	Read only on v2. Holds the document entries sent through v0. For a non-US entity, these entries count toward the one `identification_documents[]` entry it needs.
v0 error responses	Lead error registry codes and payload	The same conditions fail. Codes and the payload shape follow the error registry.

Entity Overview · Eligibility · Beneficial Ownership Requirements · The Core Account Object

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

Common individual, business, and `sole_prop` fields

`individual_details`

`business_details`

Linked entities

Identification for US and non-US entities

Documents

Address rules

Lead and partner entities

The eligibility block

Create and update

Coming from the v0 Entity API

​Common individual, business, and sole_prop fields

​individual_details

​business_details

​Linked entities

​Identification for US and non-US entities

​Documents

​Address rules

​Lead and partner entities

​The eligibility block

​Create and update

​Coming from the v0 Entity API

​Related

Common individual, business, and `sole_prop` fields

`individual_details`

`business_details`

Linked entities

Identification for US and non-US entities

Documents

Address rules

Lead and partner entities

The eligibility block

Create and update

Coming from the v0 Entity API

Related