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`
`Idempotency-Key` header	Required on POST	400 `operation_not_allowed`: `value is required but missing`

POST /v0/applications — Entity Validations (approved only)

Entity ID resolution and role validation are enforced only when status is approved.

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`

POST /v0/applications — Field Validations

Parameter	Validation Rule	Error Reason
`details.credit.currency`	Must be a valid ISO 4217 currency code	`Application is missing required currency field`
`details.credit.underwriting_grade`	Required when `status` is `approved` or `declined` for credit products	`UnderwritingGrade is required when status is approved or declined for credit products`
`details.credit.limit`	Required when `status` is `approved` for credit products	`CreditLimit is required when status is approved for credit products`
`details.credit.max_limit`	Required when `status` is `approved` for credit products	`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`	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.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`

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 will block 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. These may change via PATCH after 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

Validation	Error
`id` must match the pattern `^application_\w+$`	422 `validation_error`: `string doesn't match the regular expression "^application_\w+$"`
Application must exist	404 `not_found`: `The requested application was not found`
In-progress (non-terminal) applications are not retrievable via API	404 `url_invalid`: `The requested application was not found`

Authentication

Scenario	Error
Using an `application/read` token to call `POST /v0/applications`	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`

Foundations

API Guides

Overview

POST /v0/applications — Required Fields

POST /v0/applications — Entity Validations (approved only)

POST /v0/applications — Field Validations

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 (approved only)

​POST /v0/applications — Field Validations

​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 (approved only)

POST /v0/applications — Field Validations

Downstream Constraints — Account Creation

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

Authentication