Entity Eligibility

Eligibility is Lead’s answer to one question: which relationships can this entity hold right now? Lead computes it from the entity’s current data every time you read the entity. Lead never stores it, so fixing the data changes the answer on the next read. There is no separate request to re-run it. Eligibility appears in two places on the entity object:

intended_eligibility is optional on POST and PATCH. It’s how you tell Lead which relationship types you intend this entity to hold. When you send it, Lead checks in real time that the entity has the data each listed type needs, and rejects the request with 422 parameters_invalid if it does not.
eligibility is on every response. For each of the four relationship types, it shows whether the entity’s current data qualifies it, and which checks fail on which entity.

The four relationship types

Relationship type	Who can hold it	What it means	What it unlocks
`account_holder`	Any entity type	Full control of and legal responsibility for the user account or account number.	Being an account holder on a user account, holding account numbers, and receiving cards issued under user accounts it holds.
`minor_account_holder`	Individuals aged 16 or 17	Full control of the user account. Same requirements as `account_holder` except the age window.	Being an account holder on a user account and holding account numbers, for programs approved for minors. API only.
`authorized_signer`	Individuals only	Signs on behalf of the account holder, without legal responsibility. Common on business user accounts.	Being an authorized signer on a user account, and being listed as a beneficial owner, control person, or sole proprietor of a business entity.
`authorized_user`	Individuals only	Restricted access to the user account, without legal responsibility.	Being an authorized user on a user account and receiving cards issued under it.

business, sole_prop, lead, and partner entities are always ineligible for minor_account_holder, authorized_signer, and authorized_user, because only individuals can hold those relationships.

minor_account_holder is available only to programs approved for minor account holder support. Lead reviews the program’s intended audience, monitoring, and product controls for minors first. Contact your Technical Account Manager to request it.

Data requirements

An entity is eligible for a relationship type when it has every field listed for that type and each one passes its check. Fields not listed are optional for that type.

account_holder, individual
- individual_details.first_name, last_name
- individual_details.contact_methods with an email or phone_number in the first entry
- individual_details.date_of_birth, age 18 or older
- individual_details.address_details.physical_address
- individual_details.identification_details with tax_identification (us_entity) or at least one identification_documents[] entry (non_us_entity)
- kyc_details with result passed and a screened_at
- ofac_details with result passed and a screened_at
- risk_score
account_holder, business
- business_details.name, type, industry
- business_details.contact_methods with an email or phone_number in the first entry
- business_details.address_details.physical_address
- business_details.identification_details with tax_identification (us_entity) or at least one identification_documents[] entry (non_us_entity)
- kyc_details with result passed and a screened_at
- ofac_details with result passed and a screened_at
- risk_score
- control_persons[] with at least one entry, each with a title
- beneficial_owners[] listing every applicable owner. An empty array is valid when the business has no qualifying owners.
- Every linked control person and beneficial owner eligible for authorized_signer
account_holder, sole_prop
- business_details.name, type, industry
- business_details.contact_methods with an email or phone_number in the first entry
- business_details.address_details.physical_address
- business_details.identification_details with tax_identification (us_entity) or at least one identification_documents[] entry (non_us_entity)
- kyc_details with result passed and a screened_at
- ofac_details with result passed and a screened_at
- risk_score
- sole_proprietor, eligible for authorized_signer
minor_account_holder, individuals only
- individual_details.first_name, last_name
- individual_details.contact_methods with an email or phone_number in the first entry
- individual_details.date_of_birth, age 16 or 17
- individual_details.address_details.physical_address
- individual_details.identification_details with tax_identification (us_entity) or at least one identification_documents[] entry (non_us_entity)
- kyc_details with result passed and a screened_at
- ofac_details with result passed and a screened_at
- risk_score
authorized_signer, individuals only
- individual_details.first_name, last_name
- individual_details.contact_methods with an email or phone_number in the first entry
- individual_details.date_of_birth, age 18 or older
- individual_details.address_details.physical_address
- individual_details.identification_details with tax_identification (us_entity) or at least one identification_documents[] entry (non_us_entity)
- kyc_details with result passed and a screened_at
- ofac_details with result passed and a screened_at
authorized_user, individuals only
- individual_details.first_name, last_name
- individual_details.contact_methods with an email or phone_number in the first entry
- individual_details.identification_details.type

Reading eligibility

Every entity response carries all four keys, whatever the entity’s type.

{
  "eligibility": {
    "account_holder": {
      "status": "ineligible",
      "failed_checks": [
        {
          "check": "CheckKYCStatus",
          "entity_id": "entity_2xYv3Gq7Cj5LeS1oN6mKaA4vD8z",
          "reason": "KYC must be passed. Update kyc_details.result and kyc_details.screened_at."
        }
      ]
    },
    "minor_account_holder": {
      "status": "ineligible",
      "failed_checks": [
        {
          "check": "CheckDateOfBirthAboveMaximum",
          "entity_id": "entity_2xYv3Gq7Cj5LeS1oN6mKaA4vD8z",
          "reason": "The entity exceeds the maximum age for minor_account_holder."
        }
      ]
    },
    "authorized_signer": {
      "status": "ineligible",
      "failed_checks": [
        {
          "check": "CheckKYCStatus",
          "entity_id": "entity_2xYv3Gq7Cj5LeS1oN6mKaA4vD8z",
          "reason": "KYC must be passed. Update kyc_details.result and kyc_details.screened_at."
        }
      ]
    },
    "authorized_user": {
      "status": "eligible",
      "failed_checks": []
    }
  }
}

Each relationship type has:

Field	Type	Description
`status`	enum	`eligible` if every check passes. `ineligible` otherwise.
`failed_checks`	array	One entry per failing check. Empty when `status` is `eligible`.
`failed_checks[].check`	string	The check that failed. Use this value, not `reason`, if your code needs to handle a specific failure. The same name appears in 422 errors when you assert `intended_eligibility`.
`failed_checks[].entity_id`	string	The entity whose data failed the check. This is the entity you update.
`failed_checks[].reason`	string	A human-readable explanation and how to fix it. The wording can change, so do not parse it.

Failures on a linked entity

A business or sole proprietorship can only be eligible for account_holder if every individual linked to it is eligible for authorized_signer. When a beneficial owner, control person, or sole proprietor fails a check, the parent fails too, and failed_checks[].entity_id points at the linked individual rather than at the business. For example, a business is ineligible for account_holder because its control person failed Know Your Customer (KYC). The business’s failed_checks carries the KYC check with the control person’s entity_id. Update the control person’s entity with a passed KYC attestation. The business becomes eligible on its next read without any change to the business itself.

Asserting eligibility on a request

Send intended_eligibility to tell Lead which relationship types you intend the entity to hold. Lead checks in real time that the entity has the data each listed type needs, and rejects the request if it does not.

{
  "type": "individual",
  "intended_eligibility": ["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.", "city": "Denver", "state": "CO", "postal_code": "80014", "country": "US" }
    },
    "identification_details": {
      "type": "us_entity",
      "tax_identification": { "type": "ssn", "value": "987654321" }
    }
  },
  "kyc_details": { "result": "passed", "screened_at": "2026-06-11T14:20:00Z" },
  "ofac_details": { "result": "passed", "screened_at": "2026-06-11T14:20:00Z" }
}

What you send	What happens
`intended_eligibility` with one or more types	Lead checks the entity, after applying any update, against every listed type. If any type fails, the request returns `422 parameters_invalid` and Lead does not create or update anything. If it passes, Lead saves the list and returns it on the entity.
`intended_eligibility` omitted	On a `POST`, no check runs. On a `PATCH`, Lead checks against the saved list, if there is one.
An empty array	No check runs, and Lead clears any saved list.

A failed assertion returns every failing check for every listed type, so you can fix them in one pass. The 422 has one error per entity whose data failed, with that entity’s entity_id and its failing checks, named the same as eligibility.failed_checks[].check. When a business fails because a linked individual fails, that individual gets its own error. Field validation errors come back in the same response. Asserting is optional. An entity that meets a type’s requirements is eligible for it downstream, like on user accounts and account numbers, whether or not you asserted it. Fixing a linked individual’s data changes the eligibility of every business that lists them.

Checks

Each check verifies one data requirement.

Check	Requires	Applies to	How to fix
`CheckFirstName`	A first name	`individual`. All four types.	Set `individual_details.first_name`.
`CheckLastName`	A last name	`individual`. All four types.	Set `individual_details.last_name`.
`CheckPhoneOrEmail`	A valid email or phone number as the first entry in `contact_methods`	All entity types you create. All four types.	Put a valid email or phone number first in `contact_methods` on `individual_details` or `business_details`.
`CheckPhysicalAddress`	A physical address	All entity types you create. All but `authorized_user`.	Set `address_details.physical_address` with `line_1`, `city`, and `country`. US addresses also need `state` and a `postal_code` written as `12345`, `12345-6789`, or `12345 6789`.
`CheckDateOfBirth`	Age 18 or older	`individual`. `account_holder`, `authorized_signer`.	Set `individual_details.date_of_birth` as `YYYY-MM-DD`.
`CheckDateOfBirthBelowMinimum`	Age 16 or 17. The entity is under 16.	`individual`. `minor_account_holder`.	The entity cannot hold any account holder type until age 16.
`CheckDateOfBirthAboveMaximum`	Age 16 or 17. The entity is 18 or older.	`individual`. `minor_account_holder`.	Use `account_holder` instead. It is `eligible` if every other check passes.
`CheckDateOfBirthMissing`	A date of birth	`individual`. `minor_account_holder`.	Set `individual_details.date_of_birth` as `YYYY-MM-DD`.
`CheckGovernmentID`	A US tax ID for US entities, or another government ID for non-US entities	All entity types you create. All but `authorized_user`.	For a US individual, add a Social Security number (SSN) or Individual Taxpayer Identification Number (ITIN). For a US business or sole proprietorship, add an Employer Identification Number (EIN), SSN, or ITIN. For a non-US entity, add an entry to `identification_documents`.
`CheckOFAC`	Office of Foreign Assets Control (OFAC) screening passed, with a `screened_at` time	All entity types you create. All but `authorized_user`.	Set `ofac_details.result` to `passed` and `ofac_details.screened_at` to a past time.
`CheckKYCStatus`	KYC passed, with a `screened_at` time	All entity types you create. All but `authorized_user`.	Set `kyc_details.result` to `passed` and `kyc_details.screened_at` to a past time.
`CheckRiskScore`	A risk score	All entity types you create. `account_holder`, `minor_account_holder`.	Set `risk_score` to `low`, `medium`, or `high`.
`CheckBusinessName`	A business name	`business`, `sole_prop`. `account_holder`.	Set `business_details.name`.
`CheckBusinessType`	A business type	`business`, `sole_prop`. `account_holder`.	Set `business_details.type`.
`CheckBusinessIndustry`	One or more North American Industry Classification System (NAICS) codes	`business`, `sole_prop`. `account_holder`.	Set `business_details.industry` to valid two- to six-digit 2022 NAICS codes.
`CheckChildEntityNotFound`	Lead can load every linked owner, control person, and sole proprietor	`business`, `sole_prop`. `account_holder`.	Contact your Technical Account Manager. Lead rejects a request that links a missing or non-individual entity with `422` before this check runs.
`CheckControlPersonExists`	At least one control person, or a sole proprietor	`business`, `sole_prop`. `account_holder`.	For a business, add an entry to `control_persons` with an individual’s `entity_id` and a `title`. For a sole proprietorship, set `sole_proprietor`.
New in v2	The relationship type is held by individuals only	`business`, `sole_prop`, `lead`, `partner`. `minor_account_holder`, `authorized_signer`, `authorized_user`.	Nothing to fix. Use an individual entity for these relationship types.
New in v2	The program offers minor account holders	`individual`. `minor_account_holder`.	Contact your Technical Account Manager to request minor account holder support.
`invalid_entity`	The entity’s stored data passes Lead’s current validations. An older entity can fail this when validation rules have changed since you created it.	All entity types you create. All four types.	The `reason` names the invalid fields. Correct them with a `PATCH`.

minor_account_holder runs the full account_holder check set, including government ID, so a minor account holder needs an SSN or ITIN. The three date-of-birth checks for minors replace the 18-or-older check. Entity Overview · The Entity Object · Beneficial Ownership Requirements · Errors

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

The four relationship types

Data requirements

Reading eligibility

Failures on a linked entity

Asserting eligibility on a request

Checks

​The four relationship types

​Data requirements

​Reading eligibility

​Failures on a linked entity

​Asserting eligibility on a request

​Checks

​Related

The four relationship types

Data requirements

Reading eligibility

Failures on a linked entity

Asserting eligibility on a request

Checks

Related