> ## 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 Entity object across its three shapes — individual, business, and sole proprietorship — including attestation fields, identification rules, linkage objects, and role_details. An Entity is one object with three shapes, discriminated by `type`: `individual`, `business`, and `sole_prop`. All three share the attestation and metadata fields; they differ in their details object and in how they link to other entities. Create with `POST /v0/entities` and a required `Idempotency-Key` header (up to 255 characters). ## Common Fields (All Three Shapes) | **Attribute** | **Type** | **Description** | | :------------------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Unique Entity ID, prefixed `entity_`. Server-generated, returned on creation. | | `client_customer_id` | string (≤64) | Your identifier for the entity. **Must be unique — a create with an existing value returns 409.** Retrievable via `GET /v0/entities?client_customer_id=…`. | | `type` | enum | `individual` · `business` · `sole_prop`. Determines which details object is required. | | `intended_roles` | array | Optional synchronous role validation: `account_holder`, `minor_account_holder`, `authorized_signer`, `authorized_user`. **All-or-nothing** — if any listed role fails validation, the request fails. For `business` / `sole_prop`, pass only `account_holder`. See [Roles](/products/entity/roles) and [Troubleshooting](/products/entity/troubleshooting). | | `risk_score` | enum | `low` · `medium` · `high` — your risk score, per the mapping you provided Lead. Required for account-holder eligibility. | | `kyc_details` | object | `{ result, screened_at }` — result ∈ `pending` / `passed` / `failed`; `screened_at` must be a past timestamp. Your attestation of your KYC/KYB outcome. | | `ofac_details` | object | `{ result, screened_at }` — same enum and past-timestamp rule. Your attestation of OFAC screening. | | `rfi_details` | object | `{ result, requested_at }` — result ∈ `requested` / `completed`. Leave blank if no RFI has been sent to the customer. | | `credit_details` | array | Credit-bureau data: `credit_report_source` (`equifax` / `experian` / `transunion`) and `credit_pulled_at` required; then **exactly one of** `credit_score` (≤ 850) **or** `credit_report_non_score_value` (`unestablished` / `frozen` — for credit files without a numeric score). The entity's `credit_details` is a living record you update over time. The `details.credit.report` on an Application or Account is a point-in-time capture of the pull used for that credit decision, so the two can legitimately differ. | | `role_details` | array | **Response-only.** Per role: `name`, `status` (`active` / `inactive`), and `criteria_details[]` of `{ entity_id, failed_checks[] }` naming exactly which checks fail and on which entity — including child entities. The `minor_account_holder` entry appears only where the role is available to the program; when it is not, the entry is omitted rather than returned inactive. How to read it: [Troubleshooting](/products/entity/troubleshooting). | | `metadata` | object | Arbitrary key-value pairs. | ## `individual_details` (Required for `individual`) Required within it: `first_name`, `last_name`, and `identification_details`. First name must be at least 1 alphanumeric character. Last name must be at least 2. | **Attribute** | **Notes** | | :------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `first_name` / `middle_name` / `last_name` / `preferred_first_name` | Legal names; preferred first name optional. | | `date_of_birth` | `YYYY-MM-DD`. Account holders and authorized signers must be 18+; `minor_account_holder` requires 16–17 ([Roles](/products/entity/roles)). | | `occupation` | Optional. | | `contact_methods` | Array of `{ type: email, email }` or `{ type: phone_number, phone_number }`. Emails must be real-world `local-part@domain.tld` forms; phone numbers must follow E.123 (`+` country code with spacing — [Workflow](/products/entity/workflow#create-and-update-validations)). | | `address_details` | `physical_address`, `mailing_address`, `other_addresses[]` — see [Address Rules](#address-rules) below. | | `identification_details` | US vs. non-US — see [Identification](#identification-for-us-and-non-us-entities) below. | | `additional_documents` | Optional supporting documents: `bank_statement`, `utility_bills`, `proof_of_address`, `investigation_report`, `financial_statement`, `public_records`, `adverse_media`, `id_selfie`, `other` (with `description` required for `other`). | ## `business_details` (Required for `business` and `sole_prop`) Required within it: `name` (≥2 characters), `identification_details`, and `address_details`. | **Attribute** | **Notes** | | :---------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `corporation` · `partnership` · `sole_prop` · `llc` · `trust` · `cooperative` · `other`. **A `business` entity cannot use `sole_prop` as its business type; a `sole_prop` entity must.** | | `name` / `doing_business_as` | Legal name; DBA if operating under a different name. | | `industry` | NAICS code(s), 2–6 digits, 2022 reference files. | | `gross_annual_revenue` + `currency_code` | Prior fiscal year revenue; ISO 4217. | | `website` | Must start with `http://` or `https://`. | | `contact_methods` / `address_details` / `identification_details` / `additional_documents` | As for individuals; business identification-document types differ (formation documents, certificates of good standing, etc.). | ## Linkage Objects Resolving Ownership to People Business-family entities link to **individual** entities rather than embedding their data — create the individuals first ([Workflow](/products/entity/workflow)), then reference them: | **Object** | **On** | **Required fields** | **Notes** | | :-------------------- | :--------------------- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `beneficial_owners[]` | `business` | `entity_id` | Plus optional `ownership_percentage` (0–100.00 or 0–1.00 decimal) and `relationship_established_at`. Who must be listed, the 25% threshold, and the drill-down rule: [Beneficial Ownership Requirements](/products/entity/beneficial-ownership). An empty array is a valid submission when there are genuinely no qualifying owners. | | `control_persons[]` | `business` | `entity_id`, `title` | At least one is required for account-holder eligibility (`CheckControlPersonExists`). | | `sole_proprietor` | `sole_prop` (required) | `entity_id` | The individual behind the sole proprietorship. | Each referenced individual must meet **authorized-signer data requirements** — a child entity failing its checks makes the parent's role `inactive`, with `criteria_details` pointing at the child's `entity_id` ([Troubleshooting](/products/entity/troubleshooting)). ## Identification for US and Non-US Entities The `identification_details` object is discriminated by whether the entity has a US tax identification: * **`us_entity`** — `tax_identification` with `type` (`ssn` / `itin` / `ein`) and a 9-digit `value`. Rules: **SSNs must not start with 9** (ITINs mistakenly reported as SSNs are the most common failure); **EINs begin 00–99; ITINs begin with 9.** Individuals: `ssn` or `itin`. Businesses: `ein` — except single-member LLCs with no EIN, where `ssn` or `itin` may be used. Sole props: any of the three. * **`non_us_entity`** — at least one government-verified `identification_documents[]` entry: `type`, `identification_number`, `issuing_country` required (plus `issuing_state` for US-issued, `expiration_date`, `description` when type is `other`). Individual document types: `drivers_license`, `state_or_provincial_id`, `passport`, `permanent_residency_id`, `military_id`, `national_id`, `matriculate_id`, `other`. Business types: `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`, `other`. ## Address Rules `line_1` is the full base address — street number and street name together (or the local equivalent). Address rules protect the structure of the address, not its character set. However you collect address components from your users, **combine them into `line_1` before sending**: do not split the primary street address across lines, do not put only the number in line 1, and never pad line 1 to satisfy validation. `line_2` is only for sub-premise information (apartment, unit, suite, floor, building, care-of) — blank otherwise. `city` and `country` (ISO 3166-1 alpha-2) are required; US addresses also require a valid USPS `state` code and a 5- or 9-digit `postal_code`. Physical addresses must not be P.O. boxes, registered-agent addresses, or in prohibited countries. ## Example Entity Object ```json theme={null} { "id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "client_customer_id": "cust-000482", "created_at": "2026-06-11T14:22:05Z", "updated_at": "2026-06-11T14:22:05Z", "type": "individual", "intended_roles": ["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": "234567890" } } }, "kyc_details": { "result": "passed", "screened_at": "2026-06-11T14:20:00Z" }, "ofac_details": { "result": "passed", "screened_at": "2026-06-11T14:20:00Z" }, "role_details": [ { "name": "account_holder", "status": "active", "criteria_details": [ { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": [] } ] }, { "name": "authorized_signer", "status": "active", "criteria_details": [ { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": [] } ] }, { "name": "authorized_user", "status": "active", "criteria_details": [ { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": [] } ] }, { "name": "minor_account_holder", "status": "inactive", "criteria_details": [ { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": ["CheckDateOfBirthAboveMaximum"] } ] } ], "metadata": {} } ``` Full request/response schemas: [Create an Entity](/api-reference/endpoint/entity/create-an-entity) · [Update an Entity](/api-reference/endpoint/entity/update-an-entity).