Skip to main content

​
Use the Correct Authentication Scope

Choose the right OAuth scope before making any API call:
  • POST /v0/applications and PATCH /v0/applications/{id} require application/read_write.
  • GET /v0/applications/{id}, GET /v0/applications?client_application_id=…, and GET /v0/applications/{id}/entity_relationships accept either application/read or application/read_write.
Use the least-privileged scope appropriate to the operation. If your integration only needs to retrieve applications, use application/read and avoid provisioning broader write access.

​
Use Idempotency Keys on POST

Always include a unique Idempotency-Key header on every POST /v0/applications request. Use a UUID (e.g., 550e8400-e29b-41d4-a716-446655440000). Key behaviors to be aware of:
  • If a request fails, use a new idempotency key when retrying — the original key stores the failed response for 48 hours and replays it. Two exceptions on 409 Conflict: if the error code is idempotency_key_conflict and you have not reused this key for a different request, your identical request raced with itself — retry once with the same key to receive the original outcome. If the error code is conflict (resource modified concurrently), reload the resource and resubmit with a new key.
  • If a request succeeds (200), reusing the same idempotency key returns the cached response without creating a duplicate application.
  • Omitting the Idempotency-Key header results in a 400 operation_not_allowed error.

​
Choose the Right Status

Applications are terminal-only. At creation time, set status to the actual underwriting outcome:
  • approved — the application was approved.
  • declined — the application was declined; an adverse action notice was issued.
  • canceled — the application was withdrawn or otherwise did not reach an approval/decline decision.
If a status was reported incorrectly, correct it with PATCH /v0/applications/{id}. Because updates are subject to the same validations as creation, a correction must also carry whatever fields the new status requires — a correction to declined needs a complete details.adverse_action_notice object. See The Application Object for the mutable/immutable split. All declined and canceled applications from your program must be sent to Lead, even though Lead does not create Accounts for them, in order for Lead to ensure compliant approval processes.

​
Include All Required Status-Specific Fields

The status you choose drives which fields are required. Validate your payload against these rules before submitting:
  • declined requires a complete details.adverse_action_notice object. The adverse action notice object is all-or-nothing: if included, all three fields — delivered_at, reason, and delivery_method — must be present.
  • Every application requires a decision object with both decided_at and reason, regardless of status.
  • The details.credit object is required on every application, including non-credit products, and is_secured, is_mla, and currency are required within it. underwriting_grade is required when status is approved or declined; limit and max_limit are required on approved.
  • None of these credit-field rules inspect product type, even though several error messages say “for credit products.” A non-credit product still has to supply them.
  • details.credit.report is optional for most programs, and has its own internal requirements when you include it.
  • Each entry in documents requires document_id and type, plus a timestamp that depends on whether the type is a consent or a disclosure.
For the field-by-field rules and the error each one returns, see Validation Rules and Errors.

​
Create Entities First

The Applications API validates entity IDs on approved applications. Before calling POST /v0/applications, create the relevant entities using the Entity API and collect the entity_-prefixed IDs from those responses. Use the server-generated id (e.g., entity_3frCuaBe93vyJZxK3yOhlVuriBY) returned from the Entity API in the entities.account_holders, entities.authorized_signers, and entities.authorized_users arrays of your application request. Entity creation must be sequenced ahead of application creation — the Applications API does not create entities on your behalf. Use the intended_roles parameter on the entity creation request to confirm the entity meets the data requirements for the account_holder or authorized_signer role before you call POST /v0/applications.

​
Understand Consumer vs. Commercial Applications

account_holder_type is derived from the entity types in entities.account_holders — see Consumer vs. Commercial Account Holder Types for how the derivation and the one-category rule work. When you build the roster:
  • List individuals as authorized signers for commercial applications rather than as account holders.
  • Commercial applications require at least one entry in entities.authorized_signers, and each of those entities must have the authorized_signer role assigned. Consumer applications do not require authorized signers.

​
Retrieve Entity Relationships for Role Detail

The GET /v0/applications/{id} response returns the derived account_holder_type along with the entity ID lists on entities.account_holders and entities.authorized_signers. authorized_users is accepted on creation but is not returned on the application object. For the full relationship records, including authorized users, call:
This endpoint returns the full list of entity relationships for the application and is the authoritative source for entity association data. Entity relationships are set when the application is created and cannot be changed afterward — there is no update path for entities on an existing application.