Skip to main content
An entity is a person or business that holds or uses a Lead product. You create individual, business, or sole proprietorship entities for each of your customers and for each person who acts for them, like a beneficial owner, control person, authorized signer, or authorized user. You provide your Know Your Customer (KYC) and Know Your Business (KYB) attestation, Office of Foreign Assets Control (OFAC) screening results, and risk score for the entity. From that data, Lead computes which relationships the entity can hold. An entity does not hold money and is not a user account. It is who a user account, core account, or account number belongs to. You create the entity first, then reference its entity_id everywhere else. The Entity API also returns entities for Lead and one or more for your company. Lead sets them up during onboarding so that core accounts can name who holds them. The collection of data for your end-user first happens in your system, and the entity record is how you in turn communicate details about your end-user to Lead. See Executing vs. Reporting.
The Entity API is currently in preview with a planned beta release in December 2026. Preview APIs are not yet available in sandbox or production and can change before beta. Use these pages to plan an integration, not to build one. Once released in beta, it will be available to all partners in sandbox, and in production for select programs. Beta APIs may change without a version increment, and changes will be announced in advance. See Versioning and backwards compatibility.

​
Where entities fit in onboarding

  1. Entity API. Create an entity for each account holder, authorized signer, and authorized user, plus each beneficial owner, control person, and sole proprietor. Successful creates return an entity_id.
  2. Applications API. For underwritten credit products only. Report the final underwriting decision, referencing the entity IDs. Successful creates return an application_id.
  3. User Accounts API. Create the user account, referencing the entity IDs and, for underwritten credit, the application_id.

​
Entity types

The five types are shapes of one object. They share the same endpoints and are told apart by type. Business and sole proprietorship entities link to individual entities rather than embedding their data, so you create the individuals first. A program can have more than one partner entity, for example when your company operates through more than one legal entity. lead and partner entities exist for the life of your program. You find them by reading a core account’s account_holders, then retrieving each entity_id. There is no endpoint that lists them.

​
Eligibility

Every entity response carries eligibility. For each of four relationship types, account_holder, minor_account_holder, authorized_signer, and authorized_user, it says whether the entity’s current data qualifies it. When the entity does not qualify, eligibility lists each failing check and the entity it failed on. Lead recomputes it from the entity’s data on every read, so fixing the data is all it takes to change the answer. To have Lead reject a create or update that does not qualify, send intended_eligibility with the relationship types you plan to use. Entity Eligibility covers both fields, the data each relationship type needs, and every check. Entities have no status lifecycle. You create an entity and update it over time, and it is never deleted. The status that matters is per relationship type, inside eligibility.

​
How entities relate to the rest of the model

  • User accounts. Every account holder, authorized signer, and authorized user on a user account is an entity. Each must be eligible for the relationship type you give it. After you create the user account, you add and remove its entities with the entity relationships endpoints.
  • Applications. Every applicant, authorized signer, and authorized user on an application is an entity.
  • Core accounts. Each core account identifies its holder, which is your lead or partner entity. See The Core Account Object.
  • Account numbers. An account number identifies the entity it belongs to. That entity must be eligible for account_holder.
  • Cards. Lead issues each card to an account holder or authorized user on the user account it belongs to.

​
What you can do

  • POST /v2/entities: Create an individual, business, or sole_prop entity.
  • GET /v2/entities/{id}: Retrieve any entity, including your lead and partner entities.
  • PATCH /v2/entities/{id}: Update an entity. Some updates require a fresh KYC attestation.

​
Authentication

  • entity/read_write for create and update. Also grants read access.
  • entity/read for the GET endpoints only. Use it when your integration only needs to read entities.

​
What you cannot do

  • Create or change a lead or partner entity. A POST with either type returns 422 parameters_invalid, and a PATCH to one returns 422 operation_invalid. Ask your Technical Account Manager if your company’s name, doing-business-as name, or address needs to change.
  • Change an entity’s type. type is required on every update and must match the existing entity. Create a new entity instead.
  • Delete an entity. There is no delete endpoint. To take an entity off a user account, use DELETE /v2/user_accounts/{id}/entity_relationships/{entity_id}. The entity itself stays on record.
  • List entities. There is no list endpoint. Store the entity_id from each create.
  • Subscribe to entity webhooks. There are no entity webhook events. Read eligibility on the create or update response, or retrieve the entity.

​
In this section