> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# Applications API Best Practices

> Recommended patterns for the Lead Applications API, including OAuth scopes, idempotency keys, terminal status selection, and adverse action notice fields.

## 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, use a new idempotency key when retrying — the original key stores the failed response for 48 hours and will replay 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.

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`](https://docs.lead.bank/api-integrations/entity/troubleshooting#intended-role-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 individual entities with business or sole proprietor entities within `account_holders`. A single application may not contain both individual and business/sole proprietor account holders. Business and sole proprietor entities may be combined with each other within the same application — both produce an `account_holder_type` of `commercial`. Individuals 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:

```text theme={null}
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.