> ## 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.

# Entities: Representing Your Customers

> Legal persons or organizations related to Lead products — entity types, roles, KYC attestation, and where the Entity sits in every integration.

An **Entity** represents a legal person or organization with specific rights and roles related to Lead products. You create an Entity for each of your end customers. One is required to use credit, depository, and card products, or to be assigned an Account Number. The Entity is where Lead anchors KYC/KYB attestation, OFAC screening, RFI handling, and your risk score. It is the first object in every integration sequence: **Entity → (Application) → Account → everything else**.

## Entity Types

* **Individual** — a natural person. Create individual entities for anyone acting as an `account_holder`, `minor_account_holder`, `authorized_signer`, or `authorized_user`. Typically the individual is the account holder. Use the signer/user roles when a person needs access to an account they don't legally hold.
* **Business** — any business except a sole proprietorship. Requires linked individual entities for its beneficial owners and control person(s) — see [Beneficial Ownership Requirements](/products/entity/beneficial-ownership).
* **Sole Proprietorship** — a sole proprietorship, exempt from beneficial-ownership requirements but requiring a linked `sole_proprietor` individual.

Data requirements vary by the **role** the entity will play — a full matrix is on [Roles](/products/entity/roles).

### Worked Example: Pete's Pizza

Pete's Pizza is an LLC owned by Pete (a control person) and his wife Amanda (a beneficial owner). Pete's sister Sam is an authorized signer on the business checking account, and Daisy, an employee, is an authorized debit-card user with restricted access.

* **Pete** → individual entity, full KYC (control person)
* **Amanda** → individual entity, full KYC (beneficial owner)
* **Pete's Pizza** → business entity, full KYB + your risk assessment, linking Pete and Amanda as control person and beneficial owner
* **Sam** → individual entity, full KYC, later associated with the account as `authorized_signer`
* **Daisy** → individual entity, partial KYC (name and contact information), associated as `authorized_user`

## The Entity at a Glance

* **Identifier:** `entity_<id>`, returned on creation. You can also address an entity by your own `client_customer_id`.
* **Attestation model:** you perform KYC/KYB and OFAC screening and attest the results on the entity (`kyc_details.result` + `screened_at`, `ofac_details.result` + `screened_at`) alongside your `risk_score`. Lead validates the attestations; certain updates re-trigger KYC ([Update an Entity](/api-reference/endpoint/entity/update-an-entity)).
* **Lead computes role eligibility from the entity's data.** The entity's `role_details` array states which roles the entity currently qualifies for and why not, check by check. Pass `intended_roles` on create/update to validate synchronously instead of discovering gaps downstream. Details on [Troubleshooting](/products/entity/troubleshooting).
* **Lifecycle:** created, then updated over time. Entities stay attached to their accounts for the life of the relationship and can't be deleted.

## Endpoints

| Method  | Path                                | Purpose                                              |
| :------ | :---------------------------------- | :--------------------------------------------------- |
| `POST`  | `/v0/entities`                      | Create an individual, business, or sole-prop entity. |
| `GET`   | `/v0/entities/{id}`                 | Retrieve by Entity ID.                               |
| `GET`   | `/v0/entities?client_customer_id=…` | Retrieve by your client customer ID.                 |
| `PATCH` | `/v0/entities/{id}`                 | Update; some updates re-trigger KYC.                 |

A separate OpenAPI spec covers full request/response schemas; this page provides conceptual context.

## In This Section

* [Roles](/products/entity/roles) — the data requirements each role carries
* [Beneficial Ownership Requirements](/products/entity/beneficial-ownership) — UBOs, control persons, and the drill-down rule for business entities
* [Workflow](/products/entity/workflow) — creating and updating entities
* [Troubleshooting](/products/entity/troubleshooting) — the most common Entity API errors and how to read `role_details`