> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# The Entity Object

> Field-level reference for the v2 Entity object across its five shapes, including attestation fields, identification and documents, linked entities, the lead and partner shape, and eligibility.

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.

```json theme={null}
{
  "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](/v2/products/entity/eligibility#asserting-eligibility-on-a-request). |
| `eligibility` | object | **Response only.** Whether the entity's current data qualifies it for each relationship type, with the failing checks. See [The eligibility block](#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](/v2/products/entity/eligibility#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](#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](/products/entity/beneficial-ownership). |
| `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.

<Note>
  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.
</Note>

## 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:<br />**`individual`:** `drivers_license`, `state_or_provincial_id`, `passport`, `permanent_residency_id`, `military_id`, `national_id`, `matriculate_id`<br />**`business`:** `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`<br />**`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](https://partners.lead.bank/prohibited-countries) 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.

```json theme={null}
{
  "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](/v2/products/entity/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](/api-reference/using-the-api/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. |

## Related

[Entity Overview](/v2/products/entity/overview) · [Eligibility](/v2/products/entity/eligibility) · [Beneficial Ownership Requirements](/products/entity/beneficial-ownership) · [The Core Account Object](/products/core-account/core-account-object)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.