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.
Overview
All validation failures on the Accounts API are returned synchronously. Business logic errors return 422 responses with an invalid_parameters array that identifies which fields failed and why, so you can correct the request before retrying.
{
"code": "parameters_invalid",
"title": "Your request parameters did not validate.",
"detail": "The request is well-formed but contains semantic errors.",
"invalid_parameters": [
{
"parameter": "capabilities",
"reason": "Account is missing required capabilities field"
}
]
}
POST /v0/accounts
Required Fields
| Parameter | Validation Rule | Error Reason |
|---|
capabilities | Required; minimum 1 value | Account is missing required capabilities field |
entities.account_holders | Required; minimum 1 element | Account is missing required account_holders field |
details | Required object | property "details" is missing |
details.product_name | Required | property "product_name" is missing |
documents | Required array (empty array is valid) | Account is missing required documents field |
Idempotency-Key header | Required on POST | 400 idempotency_error: Please add the Idempotency-Key header to the request. |
Capability-Driven Validations
Capabilities determine which additional fields are required. Your program may be configured to have one or more supported_capabilities available to accounts you create.
The credit_with_underwriting capability triggers the credit validation set.
| Parameter | Validation Rule | Error Reason |
|---|
application_id | Required when capabilities include credit_with_underwriting | application_id is required for credit_with_underwriting capability |
application_id | Must reference an application in approved status | application_id is not linked to an approved application |
details.credit | Required object when capabilities include credit_with_underwriting | missing parameter details.credit, which is required for credit_with_underwriting capability |
details.credit.is_secured | Required within credit object | missing parameter is_secured, which is required for credit capabilities |
details.credit.is_mla | Required within credit object | missing parameter is_mla, which is required for credit capabilities |
details.credit.currency | Required within credit object. Must be a valid ISO 4217 code | missing parameter currency, which is required for credit capabilities |
details.credit.underwriting_grade | Required within credit object | missing parameter underwriting_grade, which is required for credit capabilities |
details.credit.available_credit | Required within credit object | missing parameter available_credit, which is required for credit capabilities |
details.credit.limit | Required within credit object | missing parameter limit, which is required for credit capabilities |
details.credit.max_limit | Required within credit object | missing parameter max_limit, which is required for credit capabilities |
Entity Validations
| Parameter | Validation Rule | Error Reason |
|---|
entities.account_holders | All entity IDs must resolve to existing entities | expected N account holder entities but only M resolved successfully; one or more entity IDs were not found |
entities.authorized_signers | All entity IDs must resolve to existing entities | expected N authorized signer entities but only M resolved successfully; one or more entity IDs were not found |
entities.authorized_users | All entity IDs must resolve to existing entities | expected N authorized user entities but only M resolved successfully; one or more entity IDs were not found |
entities.account_holders | Cannot mix individual and business/sole proprietor entity types | account holders contain mixed entity types; all must be individuals (consumer) or all must be businesses/sole proprietors (commercial) |
entities.authorized_signers | Required (min 1) when account holders are business or sole proprietor entities | Commercial account must have at least one authorized signer |
| Entity role requirements | Each entity must have the role eligibility corresponding to its relationship type | One or more entities have incorrect role assignments |
Application Match Validations
When application_id is provided, the following must match between the application and the account:
| Parameter | Validation Rule | Error Reason |
|---|
application_id | Referenced application must exist | The referenced application was not found |
application_id | Referenced application must be in approved status | application_id is not linked to an approved application |
| Account holder type | Must match between the application and the account | Account holder type does not match the linked application |
| Account holders, Authorized Signers | Must match between the Application and the Account on initial Account Creation | Account Holders and Authorized Signers must match between the application and account on account creation. These may be changed via PATCH requests over the Account's lifecycle. |
Field Validations
| Parameter | Validation Rule | Error Reason |
|---|
details.credit.report.score | If report object is provided, score is required; maximum value is 850 | CreditScore is required with credit_pulled_at and credit_report_source, maximum value is 850 |
details.credit.report.pulled_at | Required when report object is provided | CreditPulledAt is required with credit_score and credit_report_source, must be valid ISO8601 datetime |
details.credit.report.source | Required when report object is provided; must be equifax, experian, or transunion | CreditReportSource is required with credit_score and credit_pulled_at, must be one of: equifax, experian, transunion |
details.adverse_action_notice | All three AAN fields required together (delivered_at, reason, delivery_method) or none | Either all three adverse action fields are required or none |
details.adverse_action_notice | Required when status_reason is client_closed | Adverse action notice is required when status_reason is client_closed |
details.credit.scra.start_date | Required when scra object is provided | scra start_date is required when scra object is provided |
PATCH /v0/accounts/id
| Validation | Error |
|---|
Account must not be in closed status | 422 parameters_invalid: Closed accounts may not be updated |
| After applying the patch, account must still satisfy all capability-driven validations | 422 parameters_invalid with specific field errors |
documents, if provided, replaces the entire list; each entry must be a valid ComplianceDocument | 422 parameters_invalid with document-level errors |
capabilities, if provided, can only add new capabilities (existing capabilities cannot be removed) | 422 parameters_invalid: Capabilities cannot be removed from an account |
Status Transition Validations
| Endpoint | Validation Rule | Error Code |
|---|
POST /v0/accounts/{id}/deactivate | status_reason is required; must be dormant, frozen, or other | 422 parameters_invalid |
POST /v0/accounts/{id}/close | status_reason is required; must be entity_closed, client_closed, paid_off, charged_off, or canceled | 422 parameters_invalid |
GET /v0/accounts/id
| Validation | Error |
|---|
id must match the pattern ^account_\w+$ | 400 parameters_invalid: The format of the account ID is invalid. |
| Account must exist | 404: The requested account was not found |
Authentication
| Scenario | Error |
|---|
Using an account/read token to call a write endpoint (POST, PATCH) | 403 insufficient_scope |
Using an unrelated scope token (e.g., lending/read) | 403 insufficient_scope |
| Using an invalid or expired token | 403 token_invalid |
