Entity Troubleshooting

Common Errors

Four request patterns account for most errors when calling the Entity API.

Open API Spec Validation

Lead’s Entity API documentation covers our API interface specification and Lead’s raw Open API. Any request that violates this specification returns a 422, for example a POST entity request that omits a required field.

Failure of Synchronous Business Validation

Lead runs a synchronous set of business validations over Entity POST / PATCH requests. If the request violates any of those checks, the API will return a 422.

Intended Role Failure

You can pass intended_roles in a POST / PATCH request. Lead then evaluates synchronously whether the data you provided satisfies the data requirements for each listed role.If any listed role fails evaluation, the request returns a 422 that names the role check that failed. Omitting intended_roles removes the error from the create or update response, but the same gap surfaces later when you use the entity_id downstream.The checks behind these synchronous errors are identical to the checks reported in role_details on the GET entity response.

409 on Create: Duplicate client_customer_id

Each client_customer_id must be unique within your program. A POST entity request whose client_customer_id is already in use returns a 409 rather than creating a duplicate entity. Retrieve the existing entity with GET /v0/entities?client_customer_id=… and PATCH it instead of re-creating it.

Troubleshooting Role Eligibility

Role eligibility checks return a 422 only when you pass intended_roles in the POST or PATCH request. Without it, the same checks still run, and the response tells you which data requirements the entity has not yet met for each role. To find out why an entity is not eligible for a role, inspect the role_details array on the entity. It names exactly which checks fail and on which entity. The following steps show how to read a role eligibility failure and resolve it.

Find the Role and Check its Status

In the role_details array, find the object where the name matches the role you’re checking (e.g., account_holder, minor_account_holder, authorized_signer, or authorized_user).Once you’ve found the correct role object, check its status field:

active: The entity has passed all checks and is eligible for this role.
inactive: The entity is not eligible. Proceed to the next step to diagnose the failure.

Diagnose the Failure

If the status is inactive, look inside that role’s criteria_details array. This array explains what went wrong.Each object in criteria_details contains:

entity_id: The ID of the entity that has the problem and must be updated.
failed_checks: A list of one or more error codes.

Refer to the Role Check Failure table below to understand what each code in the failed_checks list means and how to resolve it.

Understand Indirect Failures (Child Entities)

Sometimes, an entity’s role is inactive because a related child entity (like a control person or beneficial owner) has failed its own required checks. The criteria_details array is designed to point you directly to that failing child entity. Example Let’s say a business is inactive for the account_holder role.

The Requirement: For a business to be an account_holder, it must list at least one control person in control_persons. That control person’s entity must, in turn, be eligible for the authorized_signer role.
The Dependency: To be an authorized_signer, the control person’s entity must have a passed KYC status.
The Failure: In this case, the control person’s entity failed its KYC check.
The Result: Because the control person is not a valid authorized_signer, the parent business cannot become an account_holder. The criteria_details for the business contains an object pointing to the control person’s entity_id with a failed_checks list containing CheckKYCStatus.

This tells you to update the control person’s entity to resolve the issue for the business entity.

business and sole_prop entities will always have an inactive status for the authorized_signer and authorized_user roles.This is expected behavior and does not indicate an error.

Role Check Failure Codes

Code	Description	Entity Type	Possible Roles	How to Resolve
`CheckFirstName`	Requires first name that is at least 1 alphanumeric character	individual	Account Holder, Authorized Signer, Authorized User	Update entity to include `individual_details.first_name`.
`CheckLastName`	Requires last name that is at least 2 alphanumeric characters	individual	Account Holder, Authorized Signer, Authorized User	Update entity to include `individual_details.last_name`.
`CheckPhoneOrEmail`	Requires valid phone number or email address	individual, business, sole_prop	Account Holder, Authorized Signer, Authorized User	For entities of type `individual`, update `individual_details.contact_methods` to include at least one email or phone number. For `business` or `sole_prop`, update `business_details.contact_methods`.
`CheckPhysicalAddress`	Requires physical address	individual, business, sole_prop	Account Holder, Authorized Signer	For `individual`, update `individual_details.address_details.physical_address`. For `business` or `sole_prop`, update `business_details.address_details.physical_address`. A physical address must include `line_1`, `city`, and `country`. If `country` is `US`, `state` and a valid 5 or 9 digit `postal_code` are also required.
`CheckDateOfBirth`	Must be 18 years or older	individual	Account Holder, Authorized Signer	Update `individual_details.date_of_birth` with the correctly formatted (YYYY-MM-DD) date, indicating the entity is over 18.
`CheckDateOfBirthBelowMinimum`	`minor_account_holder` requires age 16–17; this entity is under 16	individual	Minor Account Holder	The entity is not eligible for any account holder role until age 16.
`CheckDateOfBirthAboveMaximum`	`minor_account_holder` requires age 16–17; this entity is 18 or older	individual	Minor Account Holder	The entity meets the age requirement for `account_holder`. Check that role in `role_details` — it is active if all other criteria pass — and use `account_holder` instead.
`CheckDateOfBirthMissing`	`minor_account_holder` requires a date of birth in `YYYY-MM-DD` format	individual	Minor Account Holder	Update `individual_details.date_of_birth` with a correctly formatted (YYYY-MM-DD) date.
`CheckGovernmentID`	For US entity, requires US tax ID. For non-US, requires other government ID.	individual, business, sole_prop	Account Holder, Authorized Signer	For a US `individual`, populate `individual_details.identification_details` with a valid `ssn` or `itin`. For a US `business` or `sole_prop`, populate `business_details.identification_details` with a valid `ein`, `ssn`, or `itin`. For a non-US entity, provide documents under `identification_documents`.
`CheckOFAC`	OFAC must have passed and `ofac_details.screened_at` must be present	individual, business, sole_prop	Account Holder, Authorized Signer	`ofac_details.result` must be `passed` and `ofac_details.screened_at` must be a valid past timestamp.
`CheckKYCStatus`	KYC must have passed and `kyc_details.screened_at` must be present	individual, business, sole_prop	Account Holder, Authorized Signer	`kyc_details.result` must be `passed` and `kyc_details.screened_at` must be a valid past timestamp.
`CheckRiskScore`	Requires risk score	individual, business, sole_prop	Account Holder	`risk_score` must be populated with a value of `low`, `medium`, or `high`.
`CheckBusinessName`	Requires business name that is at least 2 alphanumeric characters	business, sole_prop	Account Holder	`business_details.name` must be populated with a value of at least 2 alphanumeric characters.
`CheckBusinessType`	Requires business type	business, sole_prop	Account Holder	`business_details.type` must be populated.
`CheckBusinessIndustry`	Requires NAICS code(s) for business industry	business, sole_prop	Account Holder	`business_details.industry` must be populated with a valid 2-6 digit 2022 NAICS code. A reference file is available at the Census Bureau.
`CheckChildEntityNotFound`	Business/sole prop must have a corresponding individual entity for owners/control persons.	business, sole_prop	Account Holder	The `entity_id` in `beneficial_owners`, `control_persons`, or `sole_proprietor` must reference a valid `individual` entity who meets `authorized_signer` data requirements.
`CheckManualReviewStatus`	Manual review is pending for at least one validation check	individual, business, sole_prop	Account Holder, Authorized Signer, Authorized User	Contact your Lead Technical Account Manager.
`CheckControlPersonExists`	Requires at least one control person for business entities	business	Account Holder	For `business` entities, the `control_persons` list must include at least one valid item referencing an `individual` entity who meets `authorized_signer` data requirements. A `title` is also required.

Intended Role Parameter

Notes for using the intended roles parameter in POST and PATCH requests or Customer File Uploads

intended_roles is an optional parameter on entity POST and PATCH requests and on Customer file records. Pass it when you believe you have captured every data point a role requires. It asks Lead to validate synchronously that the entity meets the data requirements for each listed role. This catches gaps before they cause downstream failures. Suppose the entity data you are about to send does not yet meet the Account Holder requirements:

If the request includes intended_roles: ["account_holder"], Lead rejects it with a 422 that names the failing check. Nothing is created or updated. Fix the named field and resubmit. A Customer file record that includes intended_roles fails validation the same way.

If you omit intended_roles, Lead creates the entity as long as it meets the schema requirements, even though it does not yet qualify as an account_holder. The role_details array in the response shows which roles it qualifies for, and you can update the entity later to close the gap. When a synchronous intended_roles validation fails, the 422 names the failing check using the same vocabulary as role_details. For example, an entity under 16 submitted with an intended role of minor_account_holder returns:

{
  "code": "parameters_invalid",
  "title": "Your request parameters did not validate.",
  "detail": "Entity does not meet the data requirements for minor_account_holder.",
  "invalid_parameters": [
    { "name": "intended_roles", "reason": "CheckDateOfBirthBelowMinimum" }
  ]
}

intended_roles is optional. If the entity meets a role’s data requirements and you do not pass intended_roles, Lead still treats the entity as eligible for that role in downstream use cases such as Account Number creation.

Instead of passing intended_roles, you can read role_details in the entity response as the source of truth for role eligibility.

File-Integrated Programs: Error Handling and Retry

If your program reports customers via the Customer files rather than the API, validation failures surface through the file cycle instead:

Lead posts a success message in Slack when the batch processes, listing the files it included.
If a file fails validation, the error messages appear in your Slack alert channel.
Fix the file and upload a new version. Lead re-runs validation on the latest version of each file in the batch.

Banking Infrastructure

Lending & Receivables

Payment Rails

Customers & Accounts

Network Settlement

Common Errors

Troubleshooting Role Eligibility

Understand Indirect Failures (Child Entities)

Role Check Failure Codes

Intended Role Parameter

File-Integrated Programs: Error Handling and Retry

​Common Errors

​Troubleshooting Role Eligibility

​Understand Indirect Failures (Child Entities)

​Role Check Failure Codes

​Intended Role Parameter

​File-Integrated Programs: Error Handling and Retry

Common Errors

Troubleshooting Role Eligibility

Understand Indirect Failures (Child Entities)

Role Check Failure Codes

Intended Role Parameter

File-Integrated Programs: Error Handling and Retry