> ## 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.

# The Application Object

> Field-level reference for the Application object with an example payload.

An Application is your report of a final underwriting decision. It is always in one of three terminal statuses: `approved`, `declined`, or `canceled`.

## Application Object

| **Attribute**           | **Type**  | **Description**                                                                                                                                                                                                    |
| :---------------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | string    | Unique identifier for the application. Prefixed with `application_`.                                                                                                                                               |
| `client_application_id` | string    | Read-only identifier you assigned. Present only for applications created via file upload; omitted for applications created through the API, which are identified solely by their server-generated `id`.            |
| `created_at`            | timestamp | Lead server-generated ISO 8601 timestamp when the application was created.                                                                                                                                         |
| `updated_at`            | timestamp | Lead server-generated ISO 8601 timestamp when the application was last updated.                                                                                                                                    |
| `status`                | string    | Terminal state of the application: `approved`, `declined`, or `canceled`. **There is no in-progress state**, and all three outcomes must be reported. A status reported in error can be corrected through the API. |
| `entities`              | object    | Contains information about the account holder and authorized signers. See below.                                                                                                                                   |
| `details`               | object    | Contains product, credit, and adverse action notice details. See below.                                                                                                                                            |
| `decision`              | object    | Contains information about the underwriting decision. See below.                                                                                                                                                   |
| `documents`             | array     | Document references associated with the application. See below.                                                                                                                                                    |
| `metadata`              | object    | Arbitrary key-value pairs for storing additional information.                                                                                                                                                      |

### `entities` (sub-object)

| **Attribute**         | **Type** | **Description**                                                                                                                                                                                                                                       |
| :-------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_holder_type` | string   | **Derived, never set directly.** `consumer` if all account holders are individuals; `commercial` if all are businesses or sole proprietors. The one-category rule applies: business and sole proprietor may combine, individual and business may not. |
| `account_holders`     | array    | Entity IDs that are account holders on the application. Returned on the Application object.                                                                                                                                                           |
| `authorized_signers`  | array    | Entity IDs that are authorized signers on the application. Returned on the Application object.                                                                                                                                                        |
| `authorized_users`    | array    | **Request-only.** Entity IDs to associate as authorized users. Accepted on creation but **not returned** on the Application object — retrieve it from `GET /v0/applications/{id}/entity_relationships`.                                               |

Maximum 20 entities per relationship type.

<Tip>
  The `entities` object gives you the entity IDs for account holders and authorized signers. For the full relationship records — including authorized users, which the Application object does not return — call `GET /v0/applications/{id}/entity_relationships`. It lists every relationship with its `relationship_type`: `account_holder`, `authorized_signer`, or `authorized_user`.
</Tip>

### `details` (sub-object)

| **Attribute**           | **Type** | **Description**                                                                                                                                                                |
| :---------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `product_name`          | string   | **Required.** Your internal product name. This tells Lead's Due Diligence team which product this application opens an account for if approved. Use your stable internal name. |
| `credit`                | object   | **Required on every application**, including non-credit products. Credit-specific properties. See `details.credit` below.                                                      |
| `adverse_action_notice` | object   | Adverse action notice details. **Required when `status` is `declined`.** See below.                                                                                            |

### `details.credit` (sub-object)

| **Attribute**        | **Type** | **Description**                                                                                                                                   |
| :------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| `is_secured`         | boolean  | **Always required.** `true` if the product is secured (collateral attached); `false` otherwise.                                                   |
| `is_mla`             | boolean  | **Always required.** `true` if the applicant is subject to the Military Lending Act; `false` otherwise.                                           |
| `currency`           | string   | **Required.** ISO 4217 currency code for the application (e.g., `USD`).                                                                           |
| `underwriting_grade` | string   | Your internal underwriting grade, mapped to your scoring framework. Accepts any string. **Required when `status` is `approved` or `declined`.**   |
| `limit`              | integer  | The credit limit assigned to the applicant, in minor units (e.g., cents). **Required when `status` is `approved`.**                               |
| `max_limit`          | integer  | The maximum credit limit the applicant was approved for based on original underwriting, in minor units. **Required when `status` is `approved`.** |
| `report`             | object   | Credit bureau report data. Optional for most programs. See `details.credit.report` below for its conditional requirements.                        |

### `details.credit.report` (sub-object)

The credit report is optional for most programs, but when you supply one, `pulled_at` and `source` are always required, and **exactly one of `score` or `non_score_value` must be provided** — the two are mutually exclusive.

Programs whose underwriting policy requires credit bureau data on every approval have an additional check enabled, which requires the report on approved applications. See [Validation Rules and Errors](/products/applications/validations).

| **Attribute**     | **Type**  | **Description**                                                                                                                |
| :---------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------- |
| `score`           | integer   | Credit score returned by the bureau. Supported range: 300–850. Mutually exclusive with `non_score_value`.                      |
| `non_score_value` | string    | The state of the credit file when no numeric score is available: `unestablished` or `frozen`. Mutually exclusive with `score`. |
| `pulled_at`       | timestamp | ISO 8601 timestamp when the credit report was pulled. Required whenever a report is supplied.                                  |
| `source`          | string    | Credit bureau that issued the report: `equifax`, `experian`, or `transunion`. Required whenever a report is supplied.          |

### `details.adverse_action_notice` (sub-object)

Required when `status` is `declined`. All three fields are required when the object is present.

| **Attribute**     | **Type**  | **Description**                                                              |
| :---------------- | :-------- | :--------------------------------------------------------------------------- |
| `delivered_at`    | timestamp | ISO 8601 timestamp when the adverse action notice was sent to the applicant. |
| `reason`          | string    | The reason stated in the adverse action notice.                              |
| `delivery_method` | string    | How the notice was delivered: `email`, `text`, or `other`.                   |

### `decision` (sub-object)

| **Attribute**               | **Type**  | **Description**                                                                                                                               |
| :-------------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| `decided_at`                | timestamp | ISO 8601 timestamp when the underwriting decision was made. **Required.**                                                                     |
| `reason`                    | string    | The reason for the decision. **Required.**                                                                                                    |
| `exception_approval_reason` | string    | **Provide only when the decision was an exception to your underwriting criteria** — the reason for approving outside the traditional process. |

### `documents` (array of objects)

| **Attribute**                                                                                                                                                      | **Type** | **Description** |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :-------------- |
| `document_id` and `type` are always required. Each document type is either a **disclosure** or a **consent**, and that determines which timestamp you must supply. |          |                 |

| **Attribute**  | **Type**  | **Description**                                                                                                                                                                                                           |
| :------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `document_id`  | string    | Unique identifier for the document being referenced. Use the file name of the file delivered to Lead's `/documents` SFTP directory. **Required.**                                                                         |
| `type`         | string    | Document type — for example `truth_in_lending_document`, `fcra_notice`, or `consent_to_link_account`. **Required.** See the [API Reference](/api-reference/endpoint/application/create-an-application) for the full enum. |
| `displayed_at` | timestamp | ISO 8601 timestamp when the document was displayed to the applicant. **Required for disclosure types.**                                                                                                                   |
| `consented_at` | timestamp | ISO 8601 timestamp when the applicant consented to the document. **Required for consent types.**                                                                                                                          |
| `version`      | string    | Recommended for static documents uploaded once and referenced for many applicants. Use a new `document_id` for each new version.                                                                                          |

<Note>
  Consent types — `esign_agreement`, `credit_pull_consent`, `consent_to_link_account`, `consent_to_link_hsa`, `negative_option_consent` — require `consented_at`. Every other type is a disclosure and requires `displayed_at`. Supplying the wrong timestamp for the type fails validation.
</Note>

## Mutability

`PATCH /v0/applications/{id}` accepts `status`, `details`, `decision`, `documents`, and `metadata`. `id`, `created_at`, `updated_at`, and `entities` are immutable — entities are set when the application is created, and no endpoint adds or removes entity relationships afterward.

Two behaviours to plan for: `documents` and `metadata` **replace wholesale rather than merging**, so send the full intended array or object. And every update runs the same validations as creation, so a correction to `declined` must also carry `details.adverse_action_notice`.

For merge-patch semantics, the per-field notes, and the `422` behaviour on immutable fields, see [Update an Application](/api-reference/endpoint/application/update-an-application).

## Example Application Object

```json theme={null}
{
  "id": "application_xyz123",
  "created_at": "2026-05-14T15:59:30Z",
  "updated_at": "2026-05-14T15:59:30Z",
  "status": "approved",
  "entities": {
    "account_holder_type": "commercial",
    "account_holders": ["entity_abc123"],
    "authorized_signers": ["entity_def456"]
  },
  "details": {
    "product_name": "Growth Business Credit Line",
    "credit": {
      "is_secured": false,
      "is_mla": false,
      "currency": "USD",
      "underwriting_grade": "99",
      "limit": 5000000,
      "max_limit": 10000000,
      "report": {
        "score": 712,
        "pulled_at": "2026-05-14T15:58:40Z",
        "source": "transunion"
      }
    }
  },
  "decision": {
    "decided_at": "2026-05-14T15:59:12Z",
    "reason": "Meets program underwriting criteria"
  },
  "documents": [
    {
      "document_id": "document_2N5Hk8xYmQpL9rBvC3jD",
      "type": "truth_in_lending_document",
      "displayed_at": "2026-05-14T15:58:05Z",
      "version": "v1"
    },
    {
      "document_id": "document_7Qw2Rt5YuI9oP3aS6dF1",
      "type": "consent_to_link_account",
      "consented_at": "2026-05-14T15:57:20Z"
    }
  ],
  "metadata": {}
}
```

Full request schemas, including status-conditional requirements, are in the [API Reference](/api-reference/endpoint/application/create-an-application) and [Validation Rules and Errors](/products/applications/validations).