Accounts API Validation Rules and Errors

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`
`capabilities`	`credit_with_underwriting` requires at least one account holder with adult `account_holder` role eligibility. An account cannot add credit capabilities if every account holder is eligible only for `minor_account_holder`. Evaluated on POST, and on PATCH when `capabilities` is supplied.	`Account requires at least one adult account_holder-eligible account holder (account_requires_adult_account_holder)`

The adult account holder check evaluates computed role eligibility — the same evaluation surfaced in the Entity API’s role_details — not the intended_roles submitted at entity creation. An adult authorized_signer on the account does not satisfy this requirement; the adult must hold account_holder eligibility. Any account_holder-eligible entity — an individual 18 or older, or a business or sole proprietorship — satisfies it.

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. `entities.account_holders` may resolve to entities with either `account_holder` or, for approved programs, `minor_account_holder` eligibility.	`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`
If `capabilities` adds `credit_with_underwriting`, the account must include at least one adult `account_holder`-eligible account holder	422 `parameters_invalid`: `account_requires_adult_account_holder`

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`

Banking Infrastructure

Funding & Settlement

Payment Rails

Customers & Accounts

Overview

POST /v0/accounts

Required Fields

Capability-Driven Validations

Entity Validations

Application Match Validations

Field Validations

PATCH /v0/accounts/id

Status Transition Validations

GET /v0/accounts/id

Authentication

​Overview

​POST /v0/accounts

​Required Fields

​Capability-Driven Validations

​Entity Validations

​Application Match Validations

​Field Validations

​PATCH /v0/accounts/id

​Status Transition Validations

​GET /v0/accounts/id

​Authentication

Overview

POST /v0/accounts

Required Fields

Capability-Driven Validations

Entity Validations

Application Match Validations

Field Validations

PATCH /v0/accounts/id

Status Transition Validations

GET /v0/accounts/id

Authentication