Skip to main content

​
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

ParameterValidation RuleError Reason
statusRequired; must be approved, declined, or canceledStatus must be one of: approved, declined, canceled
entities.account_holdersRequired; minimum 1 elementApplication is missing required account_holders field
detailsRequired objectproperty "details" is missing
documentsRequired arrayApplication is missing required documents field
decisionRequired objectproperty "decision" is missing
Idempotency-Key headerRequired on POST400 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.
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.account_holdersCannot 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_signersRequired (min 1) when account holders are Business or Sole Prop entitiesCommercial application must have at least one authorized signer
entities.authorized_signersEntities must have the authorized_signer roleOne or more authorized signer entities have incorrect role assignments

​
POST /v0/applications — Field Validations

ParameterValidation RuleError Reason
details.credit.currencyMust be a valid ISO 4217 currency codeApplication is missing required currency field
details.credit.underwriting_gradeRequired when status is approved or declined for credit productsUnderwritingGrade is required when status is approved or declined for credit products
details.credit.limitRequired when status is approved for credit productsCreditLimit is required when status is approved for credit products
details.credit.max_limitRequired when status is approved for credit productsMaxCreditLimit is required when status is approved for credit products
details.credit.limitCannot exceed details.credit.max_limit for approved applicationsCreditLimit must not exceed MaxCreditLimit for approved credit products
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_notice.delivered_atRequired when status is declinedAANDeliveredAt must be valid ISO8601 datetime when status is declined
details.adverse_action_notice.reasonRequired when status is declinedAANReason is required when status is declined
details.adverse_action_notice.delivery_methodRequired when status is declined; must be email, text, or otherAANDeliveryMethod 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.
ConstraintValidation RuleError Reason
account_holder_typeMust match the applicationAccount holder type does not match the linked application
Account holders and Authorized SignersMust 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 statusMust be approved when the application is referenced as application_id on an accountapplication_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

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

​
Authentication

ScenarioError
Using an application/read token to call POST /v0/applications403 insufficient_scope
Using an unrelated scope token (e.g., account_number/read)403 insufficient_scope
Using an invalid or expired token403 token_invalid