Applications API Validation Rules and Errors

Overview

All validation failures on the Applications API are returned synchronously. Business logic errors are returned as 422 responses with an invalid_parameters array that identifies which fields failed and why, so you can correct the request before retrying.

{
  "error_type": "invalid_parameters",
  "error_message": "One or more parameters are invalid.",
  "invalid_parameters": [
    {
      "parameter": "<parameter>",
      "reason": "<reason>"
    }
  ]
}

POST /v0/applications — Required Fields

Parameter	Validation Rule	Error Reason
`status`	Required; must be `approved`, `declined`, or `canceled`	`Status must be one of: approved, declined, canceled`
`entities.account_holders`	Required; minimum 1 element	`Application is missing required account_holders field`
`details`	Required object	`property "details" is missing`
`documents`	Required array	`Application is missing required documents field`
`decision`	Required object	`property "decision" is missing`
`details.credit`	Required object on every application, including non-credit products	Schema validation: `details.credit` is required
`Idempotency-Key` header	Required on POST	400 `operation_not_allowed`: `value is required but missing`

POST /v0/applications — Entity Validations

Most entity checks are enforced only when status is approved — a declined or canceled application does not surface them, so an entity problem can stay hidden until your first approval. The duplicate checks are the exception and run on every status.

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.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 Prop entities	`Commercial application must have at least one authorized signer`
`entities.authorized_signers`	Entities must have the `authorized_signer` role	`One or more authorized signer entities have incorrect role assignments`
`entities.account_holders`	Entities must have an active `account_holder` role	Error code `app_account_holder_invalid_role`
`entities.account_holders`	Must reference unique entities after resolution. Enforced on every status, not just approved	Error code `app_account_holder_duplicate_entities`
`entities.authorized_signers`	Must reference unique entities after resolution. Enforced on every status, not just approved	Error code `app_authorized_signer_duplicate_entities`

POST /v0/applications — Field Validations

Several error messages below say “for credit products” — underwriting_grade, limit, max_limit, and is_mla. None of these rules inspect product type. underwriting_grade, limit, and max_limit are gated on status alone; is_mla and the details.credit object are required on every application. Do not read the error text as an exemption for non-credit products.

Parameter	Validation Rule	Error Reason
`details.product_name`	Required	`Application is missing required product_name field`
`details.credit.currency`	Required; must be a valid ISO 4217 currency code	`Application is missing required currency field`
`details.credit.is_secured`	Always required; must be a boolean	`IsSecured field must be a boolean value (true/false)`
`details.credit.is_mla`	Always required; must be a boolean	`IsMLA must be a boolean value (true/false) when status is approved or declined for credit products`
`details.credit.underwriting_grade`	Required when `status` is `approved` or `declined`	`UnderwritingGrade is required when status is approved or declined for credit products`
`details.credit.limit`	Required when `status` is `approved`	`CreditLimit is required when status is approved for credit products`
`details.credit.max_limit`	Required when `status` is `approved`	`MaxCreditLimit is required when status is approved for credit products`
`details.credit.limit`	Cannot exceed `details.credit.max_limit` for approved applications	`CreditLimit must not exceed MaxCreditLimit for approved credit products`
`details.credit.report.score`	When `report` is provided, required unless `non_score_value` is supplied; mutually exclusive with `non_score_value`; must be non-zero and within 300–850	`CreditScore is required with credit_pulled_at and credit_report_source, allowed range is 300-850`
`details.credit.report.non_score_value`	Alternative to `score` when no numeric score is available; must be `unestablished` or `frozen`; mutually exclusive with `score`	`CreditReportNonScoreValue must be one of: unestablished, frozen; mutually exclusive with credit_score`
`details.credit.report.pulled_at`	Required whenever `report` is provided	`CreditPulledAt is required with credit_score and credit_report_source, must be valid ISO8601 datetime`
`details.credit.report.source`	Required whenever `report` 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.delivered_at`	Required when `status` is `declined`	`AANDeliveredAt must be valid ISO8601 datetime when status is declined`
`details.adverse_action_notice.reason`	Required when `status` is `declined`	`AANReason is required when status is declined`
`details.adverse_action_notice.delivery_method`	Required when `status` is `declined`; must be `email`, `text`, or `other`	`AANDeliveryMethod must be one of: email, text, other when status is declined`
`decision.decided_at`	Required on every application, whatever the status	`DecidedAt is required when status is approved, declined, or canceled`
`decision.reason`	Required on every application, whatever the status	`DecisionReason is required when status is approved, declined, or canceled`
`details.credit.report`	Presence of credit bureau data is required on approved applications for programs where this check is enabled — see below	`Credit bureau data (credit_score or credit_report_non_score_value, credit_pulled_at, credit_report_source) is required when application status is approved`

The credit bureau presence check is off by default. It requires that an approved application carry pulled_at, source, and one of score / non_score_value, but it is enabled per program rather than globally. If your program’s underwriting policy requires bureau data on every approval, expect it to be on; otherwise details.credit.report remains optional. The field-level rules above still apply whenever you do send a report.

POST /v0/applications — Document Validations

Every document type is either a consent or a disclosure, and that determines which timestamp is required. Document failures are reported against the documents array as a whole rather than per entry, with the reason Documents do not conform to schema specification. The rules below are what that message covers — check each entry against all of them.

Parameter	Validation Rule
`documents[].document_id`	Required on every entry
`documents[].type`	Required; must be a valid document type — see the API Reference for the full enum
`documents[].consented_at`	Required when `type` is a consent type: `esign_agreement`, `credit_pull_consent`, `consent_to_link_account`, `consent_to_link_hsa`, `negative_option_consent`
`documents[].displayed_at`	Required when `type` is any other (disclosure) type

PATCH /v0/applications/id

PATCH uses JSON Merge Patch semantics (RFC 7396) and applies the same field validations documented above for POST /v0/applications. A correction to declined must therefore carry a complete details.adverse_action_notice object, just as it does on creation.

Validation	Error
`status`, `details`, `decision`, `documents`, and `metadata` are mutable	—
`id`, `created_at`, `updated_at`, and `entities` are immutable	422 `parameters_invalid` with the offending field in `invalid_parameters`
`documents` and `metadata` replace wholesale rather than merging	—
`Idempotency-Key` header	Required on `PATCH`

See The Application Object for a summary, or Update an Application for the per-field detail.

Downstream Constraints — Account Creation

When you later use an approved application to create an Account, the Accounts API enforces matching between the application and the account. The rules below run on POST /v0/accounts, not on POST /v0/applications, but a mismatch blocks account creation against this application — design the roster on the application accordingly.

Constraint	Validation Rule	Error Reason
`account_holder_type`	Must match the application	Account holder type does not match the linked application
Account Holders and 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.
Application `status`	Must be `approved` when the application is referenced as `application_id` on an account	application_id is not linked to an approved application

See the Accounts API validations for the canonical application-match rules.

GET /v0/applications/id and GET /v0/applications/id/entity_relationships

Applications created through the API are always terminal. Applications created by file upload can carry a non-terminal status, and those records are not retrievable through the API.

Validation	Error
`id` must match the pattern `^application_\w+$`	422 `validation_error`: `string doesn't match the regular expression "^application_\w+$"`
A `client_application_id` you assigned cannot be used on the path form — retrieve it with `GET /v0/applications?client_application_id=…`	422 `validation_error` on `id`
Application must exist	404 `not_found`: `The requested application was not found`
An application created by file upload that never reached a terminal status is not retrievable through the API	404 `url_invalid`: `The requested application was not found`

Authentication

Scenario	Error
Using an `application/read` token to call `POST /v0/applications` or `PATCH /v0/applications/{id}`	403 `insufficient_scope`
Using an unrelated scope token (e.g., `account_number/read`)	403 `insufficient_scope`
Using an invalid or expired token	403 `token_invalid`

Banking Infrastructure

Lending & Receivables

Payment Rails

Customers & Accounts

Network Settlement

Overview

POST /v0/applications — Required Fields

POST /v0/applications — Entity Validations

POST /v0/applications — Field Validations

POST /v0/applications — Document Validations

PATCH /v0/applications/id

Downstream Constraints — Account Creation

GET /v0/applications/id and GET /v0/applications/id/entity_relationships

Authentication

​Overview

​POST /v0/applications — Required Fields

​POST /v0/applications — Entity Validations

​POST /v0/applications — Field Validations

​POST /v0/applications — Document Validations

​PATCH /v0/applications/id

​Downstream Constraints — Account Creation

​GET /v0/applications/id and GET /v0/applications/id/entity_relationships

​Authentication

Overview

POST /v0/applications — Required Fields

POST /v0/applications — Entity Validations

POST /v0/applications — Field Validations

POST /v0/applications — Document Validations

PATCH /v0/applications/id

Downstream Constraints — Account Creation

GET /v0/applications/id and GET /v0/applications/id/entity_relationships

Authentication