Entities: Representing Your Customers

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

​

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).
• 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.
• Lifecycle: created, then updated over time. Entities stay attached to their accounts for the life of the relationship and can’t be deleted.

​

Endpoints

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

​

In This Section

• Roles — the data requirements each role carries
• Beneficial Ownership Requirements — UBOs, control persons, and the drill-down rule for business entities
• Workflow — creating and updating entities
• Troubleshooting — the most common Entity API errors and how to read role_details