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

# Entity Eligibility

> The four relationship types an entity can hold, the data each requires, how to read eligibility, and how intended_eligibility rejects a request that does not qualify.

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.

<Note>
  `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.
</Note>

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

## Related

[Entity Overview](/v2/products/entity/overview) · [The Entity Object](/v2/products/entity/entity-object) · [Beneficial Ownership Requirements](/products/entity/beneficial-ownership) · [Errors](/api-reference/using-the-api/errors)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.