Skip to main content

​
Common Errors

Three request patterns reflect the most common errors for callers of the Entity API.
Lead’s Entity API documentation covers our API interface specification and Lead’s raw Open API spec can be found here . Any request that violates this specification will return a 422 — for example failing to include a required field in a POST entity request.
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.
You may specify an intended_role in a POST / PATCH request. This triggers a synchronous evaluation of whether the data points being provided satisfy the data requirements for the specified role.Failed role evaluations when the intended_roles parameter is part of the request will return a 422 that specifies the role check that failed. Of course, removing the intended_role will eliminate the error, but then the error will be surfaced when the entity_id is passed in a downstream use-case.Synchronous errors surfaced through the use of the intended_role parameter are identical to checks evaluated in the role_details of the GET entity response.

​
Troubleshooting Role Eligibility

While Role Eligibility checks only surface 422 responses if the intended_roles parameter is used in the POST or PATCH entity request, they do surface information to callers about additional data requirements that must be met in order to fulfill a particular entity use case. To determine why an entity is not eligible for a role, you’ll inspect the role_details array within the entity object. This process will tell you exactly which checks are failing and for which entity. See the following steps for determining how to interpret role eligibility failures and handle them to unlock entity use cases as needed.
1

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, 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.
2

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.
  1. The Requirement: For a business to be an account_holder, it must have a control_person. That control_person entity must, in turn, be eligible for the authorized_signer role.
  2. The Dependency: To be an authorized_signer, the control_person entity must have a passed KYC status.
  3. The Failure: In this case, the control_person entity failed their KYC check.
  4. 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 will contain an object pointing to the control_person’s entity_id with a failed_checks list containing CheckKYCStatus.
This tells you that you must update the control_person 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

CodeDescriptionEntity TypePossible RolesHow to Resolve
CheckFirstNameRequires first name that is at least 1 alphanumeric characterindividualAccount Holder, Authorized Signer, Authorized UserUpdate entity to include individual_details.first_name.
CheckLastNameRequires last name that is at least 2 alphanumeric charactersindividualAccount Holder, Authorized Signer, Authorized UserUpdate entity to include individual_details.last_name.
CheckPhoneOrEmailRequires valid phone number or email addressindividual, business, sole_propAccount Holder, Authorized Signer, Authorized UserFor 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.
CheckPhysicalAddressRequires physical addressindividual, business, sole_propAccount Holder, Authorized SignerFor individual, update individual_details.addresses.physical_address. For business or sole_prop, update business_details.addresses.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.
CheckDateOfBirthMust be 18 years or olderindividualAccount Holder, Authorized SignerUpdate individual_details.date_of_birth with the correctly formatted (YYYY-MM-DD) date, indicating the entity is over 18.
CheckGovernmentIDFor US entity, requires US tax ID. For non-US, requires other government ID.individual, business, sole_propAccount Holder, Authorized SignerFor 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.
CheckOFACOFAC must have passed and ofac_screened_at must be presentindividual, business, sole_propAccount Holder, Authorized Signerofac_details.result must be passed and ofac_details.screened_at must be a valid past timestamp.
CheckKYCStatusKYC must have passed and kyc_screened_at must be presentindividual, business, sole_propAccount Holder, Authorized Signerkyc_details.result must be passed and kyc_details.screened_at must be a valid past timestamp.
CheckRiskScoreRequires risk scoreindividual, business, sole_propAccount Holderrisk_score must be populated with a value of low, medium, or high.
CheckBusinessNameRequires business name that is at least 2 alphanumeric charactersbusiness, sole_propAccount Holderbusiness_details.business_name must be populated with a value of at least 2 alphanumeric characters.
CheckBusinessTypeRequires business typebusiness, sole_propAccount Holderbusiness_details.type must be populated.
CheckBusinessIndustryRequires NAICS code(s) for business industrybusiness, sole_propAccount Holderbusiness_details.industry must be populated with a valid 2-6 digit 2022 NAICS code. A reference file is available at the Census Bureau.
CheckChildEntityNotFoundBusiness/sole prop must have a corresponding individual entity for owners/control persons.business, sole_propAccount HolderThe entity_id in beneficial_owners, control_persons, or sole_proprietor must reference a valid individual entity who meets authorized_signer data requirements.
CheckManualReviewStatusManual review is pending for at least one validation checkindividual, business, sole_propAccount Holder, Authorized Signer, Authorized UserContact your Lead Technical Account Manager.
CheckControlPersonExistsRequires at least one control person for business entitiesbusinessAccount HolderFor 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 that may be used when sending an Entity Record to Lead. It should be used when, as a caller, you believe you have captured all necessary data points to satisfy a Role Use Case. By using this parameter, you are asking Lead to synchronously validate that an Entity meets the Data Requirements for the intended use-case. This prevents downstream failures. For instance, if an Entity is created without sufficient data requirements for the Account Holder role is created
If intended_roles: [account_holder] is part of the request, the Entity upload will fail (and via API, you will return a 4xx response)
If intended_roles is not part of the request, and the Entity creation meets all minimal schema requirements, but not the data requirements necessary for a particular role, Lead will successfully ingest the entity record. The role_details parameter of the entity response will confirm which roles the entity meets necessary data requirements for.
intended_roles is a purely optional synchronous validation.If the Account Holder (or other roles) data requirements are met, and you do not pass the intended_roles parameter, Lead will still successfully consider the entity eligible for the Account Holder (or other roles) role in downstream use cases such as Account Number creation.
An alternative to providing the intended_roles parameter is to check the role_details parameter in the entity response as a source of truth for Account Holder eligibility.

​
Error Handling and Retry

  1. You will get a success message in Slack if the batch of files work with the list of files
  2. Upon invalid file upload you will see the error messages in your Slack alert channel
  3. You can fix the batch by updating the version of the file that needed to be fixed and upload it again. Lead will kick off validation for the latest version of each file in the batch.