Skip to main content

​
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

ParameterValidation RuleError Reason
capabilitiesRequired; minimum 1 valueAccount is missing required capabilities field
entities.account_holdersRequired; minimum 1 elementAccount is missing required account_holders field
detailsRequired objectproperty "details" is missing
details.product_nameRequiredproperty "product_name" is missing
documentsRequired array (empty array is valid)Account is missing required documents field
Idempotency-Key headerRequired on POST400 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.
ParameterValidation RuleError Reason
application_idRequired when capabilities include credit_with_underwritingapplication_id is required for credit_with_underwriting capability
application_idMust reference an application in approved statusapplication_id is not linked to an approved application
details.creditRequired object when capabilities include credit_with_underwritingmissing parameter details.credit, which is required for credit_with_underwriting capability
details.credit.is_securedRequired within credit objectmissing parameter is_secured, which is required for credit capabilities
details.credit.is_mlaRequired within credit objectmissing parameter is_mla, which is required for credit capabilities
details.credit.currencyRequired within credit object. Must be a valid ISO 4217 codemissing parameter currency, which is required for credit capabilities
details.credit.underwriting_gradeRequired within credit objectmissing parameter underwriting_grade, which is required for credit capabilities
details.credit.available_creditRequired within credit objectmissing parameter available_credit, which is required for credit capabilities
details.credit.limitRequired within credit objectmissing parameter limit, which is required for credit capabilities
details.credit.max_limitRequired within credit objectmissing parameter max_limit, which is required for credit capabilities

​
Entity Validations

ParameterValidation RuleError Reason
entities.account_holdersAll entity IDs must resolve to existing entitiesexpected N account holder entities but only M resolved successfully; one or more entity IDs were not found
entities.authorized_signersAll entity IDs must resolve to existing entitiesexpected N authorized signer entities but only M resolved successfully; one or more entity IDs were not found
entities.authorized_usersAll entity IDs must resolve to existing entitiesexpected N authorized user entities but only M resolved successfully; one or more entity IDs were not found
entities.account_holdersCannot mix individual and business/sole proprietor entity typesaccount holders contain mixed entity types; all must be individuals (consumer) or all must be businesses/sole proprietors (commercial)
entities.authorized_signersRequired (min 1) when account holders are business or sole proprietor entitiesCommercial account must have at least one authorized signer
Entity role requirementsEach entity must have the role eligibility corresponding to its relationship typeOne 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:
ParameterValidation RuleError Reason
application_idReferenced application must existThe referenced application was not found
application_idReferenced application must be in approved statusapplication_id is not linked to an approved application
Account holder typeMust match between the application and the accountAccount holder type does not match the linked application
Account holders, Authorized SignersMust match between the Application and the Account on initial Account CreationAccount 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

ParameterValidation RuleError Reason
details.credit.report.scoreIf report object is provided, score is required; maximum value is 850CreditScore is required with credit_pulled_at and credit_report_source, maximum value is 850
details.credit.report.pulled_atRequired when report object is providedCreditPulledAt is required with credit_score and credit_report_source, must be valid ISO8601 datetime
details.credit.report.sourceRequired when report object is provided; must be equifax, experian, or transunionCreditReportSource is required with credit_score and credit_pulled_at, must be one of: equifax, experian, transunion
details.adverse_action_noticeAll three AAN fields required together (delivered_at, reason, delivery_method) or noneEither all three adverse action fields are required or none
details.adverse_action_noticeRequired when status_reason is client_closedAdverse action notice is required when status_reason is client_closed
details.credit.scra.start_dateRequired when scra object is providedscra start_date is required when scra object is provided

​
PATCH /v0/accounts/id

ValidationError
Account must not be in closed status422 parameters_invalid: Closed accounts may not be updated
After applying the patch, account must still satisfy all capability-driven validations422 parameters_invalid with specific field errors
documents, if provided, replaces the entire list; each entry must be a valid ComplianceDocument422 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

EndpointValidation RuleError Code
POST /v0/accounts/{id}/deactivatestatus_reason is required; must be dormant, frozen, or other422 parameters_invalid
POST /v0/accounts/{id}/closestatus_reason is required; must be entity_closed, client_closed, paid_off, charged_off, or canceled422 parameters_invalid

​
GET /v0/accounts/id

ValidationError
id must match the pattern ^account_\w+$400 parameters_invalid: The format of the account ID is invalid.
Account must exist404: The requested account was not found

​
Authentication

ScenarioError
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 token403 token_invalid