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 do not 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.

These types are shapes of one object — same endpoints, discriminated by type — and business-family entities link to individual entities rather than embedding their data (The Entity Object). Data requirements vary by the role the entity will play — the 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 — which must be unique: creating a second entity with the same one returns a 409.
• 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 (Workflow).
• Lead computes role eligibility from the entity’s data. The entity’s role_details array states which roles the entity currently qualifies for and — check by check — why not. Pass intended_roles on create/update to validate synchronously instead of discovering gaps downstream. How to read it: Troubleshooting.
• Lifecycle: created, then updated over time. Entities stay attached to their accounts for the life of the relationship and cannot be deleted — which is why the Entity has no statuses page; the statuses that matter are per-role, inside role_details.

​

Endpoints

​

In This Section

• The Entity Object — every field across the three entity shapes, with an example payload
• Roles — the data requirements each role carries
• Beneficial Ownership Requirements — UBOs, control persons, and the drill-down rule
• Workflow — creating and updating entities, and the point-of-entry validations
• Troubleshooting — the most common Entity API errors and how to read role_details