Overview
All validation failures on the Accounts API are returned synchronously. Business logic errors return422 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. Thecredit_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 entities with business or sole_prop entities. business and sole_prop entities may be combined. | account holders contain mixed entity categories; all must be individuals (consumer) or all must be business and/or sole_prop (commercial). business and sole_prop entities may be combined within the commercial category. |
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
Whenapplication_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 |