Skip to main content

​
Use the Correct Authentication Scope

Choose the right OAuth scope before making any API call:
  • POST /v0/applications requires application/read_write.
  • GET /v0/applications/{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 with a 4xx error (except 409 Conflict), the idempotency key was not consumed. Generate a new key before retrying — the same key can only be reused for the exact same request body.
  • 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.
The status of an existing application cannot currently be changed after a POST /v0/applications request. If a status was reported incorrectly, you must reach out to Lead’s team directly. All declined and canceled applications from your program must be sent to Lead, even though Accounts will not be created 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.
  • approved and declined require a decision object with both decided_at and reason.
  • details.credit.report is optional, but if included, all three fields — score, pulled_at, and source — must be provided together. This object is also all-or-nothing. For programs where credit reports are a required component of underwriting, details.credit.report is enforced as required for approved applications.

​
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 and entities.authorized_signers arrays of your application request. Entity creation must be sequenced ahead of application creation — the Applications API will not create entities on your behalf. You should utilize the intended_roles parameter on the entity creation request to ensure the Entity meets necessary data requirements to be an account_holder or authorized_signer for an approved application prior to attempting to call POST /v0/applications.

​
Understand Consumer vs. Commercial Applications

The account_holder_type field (consumer or commercial) is derived automatically from the entity types in entities.account_holders — you do not set it directly:
  • Individual entities produce consumer.
  • Business or sole proprietor entities produce commercial.
Do not mix entity types within account_holders. A single application may not contain both individual and business/sole proprietor account holders. (It may contain both business and sole_proprietor account holders). Indivuals should be listed as authorized signers for commercial applications rather than account holders. Commercial applications (those with business or sole proprietor account holders) require at least one entry in entities.authorized_signers. Each authorized signer entity must have the authorized_signer role assigned. Consumer applications do not require authorized signers.

​
Retrieve Entity Relationships Separately

The GET /v0/applications/{id} response includes the derived account_holder_type but does not return the underlying entity ID lists. To see which specific entities are linked to an application and in which role (account_holder or authorized_signer), call: 
GET /v0/applications/{id}/entity_relationships
This endpoint returns the full list of entity relationships for the application and is the authoritative source for entity association data.