> ## 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 v2 Application object, including entities, underwriting and decision details, Files API document references, and legacy documents.

An application is your report of a final underwriting decision. You create one with `POST /v2/applications` and read it with `GET /v2/applications/{id}`.

```json theme={null}
{
  "id": "application_2xYv5Rt8Lm1NpQ4kW9zXcV7bH3j",
  "status": "approved",
  "product_name": "Growth Business Credit Line",
  "entities": {
    "account_holder_type": "commercial",
    "account_holders": ["entity_9f3cKq2Lm8Nw4Rx7Tz1Ba5Ce0D"],
    "authorized_signers": ["entity_4dP7Hs2Jk9Lm3Qw8Ex6Rt1Yu5I"]
  },
  "details": {
    "underwriting": {
      "is_secured": false,
      "is_mla": false,
      "currency_code": "USD",
      "underwriting_grade": "A2",
      "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": [
    { "file_id": "file_2N5Hk8xYmQpL9rBvC3jD", "timestamp": "2026-05-14T15:58:05Z", "version": "v1" },
    { "file_id": "file_7Qw2Rt5YuI9oP3aS6dF1", "timestamp": "2026-05-14T15:57:20Z" }
  ],
  "metadata": {},
  "created_at": "2026-05-14T15:59:30Z",
  "updated_at": "2026-05-14T15:59:30Z"
}
```

## Fields

| **Field** | **Type** | **Description** |
| :- | :- | :- |
| `id` | string | Unique ID, prefixed `application_`. Lead generates it on create. |
| `client_application_id` | string | Read only. Your ID for applications you reported in an Application file. Lead omits it for applications created through the API, which you identify by `id`. |
| `status` | enum | `approved`, `declined`, or `canceled`. Always a final outcome. See [Application Statuses](/v2/products/applications/statuses). |
| `product_name` | string | **Required.** Your internal product name. It tells Lead which product the application opens a user account for if approved. Use a stable name. |
| `entities` | object | The entities on the application. See [`entities`](#entities). |
| `details` | object | Underwriting and adverse action notice details. See [`details`](#details). |
| `decision` | object | When and why the decision was made. See [`decision`](#decision). |
| `documents` | array | Compliance documents for the application, each referencing a file you uploaded. See [`documents`](#documents). |
| `legacy_documents` | array | **Response only.** Document entries sent through v0, on applications created on v0. |
| `metadata` | object | Key-value pairs for your own use. |
| `created_at`, `updated_at` | timestamp | RFC 3339, UTC. Lead sets them. |

## `entities`

| **Field** | **Type** | **Description** |
| :- | :- | :- |
| `account_holder_type` | enum | **Response only.** `consumer` if every account holder is an individual. `commercial` if every account holder is a business or sole proprietorship. Lead derives it, and you cannot set it. |
| `account_holders` | array | Entity IDs of the applicants. Required, at least one. On `approved` applications, each must be eligible for `account_holder`. |
| `authorized_signers` | array | Entity IDs of authorized signers. On `approved` applications, each must be eligible for `authorized_signer`, and a commercial application needs at least one. |
| `authorized_users` | array | Request only. Entity IDs of authorized users. Lead accepts it on create and does not return it on the application. List them with `GET /v2/applications/{id}/entity_relationships`. |

Each relationship type takes up to 20 entities. On every status, Lead checks that each entity exists, that no entity appears twice in one relationship type, and that the account holders are all consumer or all commercial. On `approved` applications only, Lead also checks each entity's eligibility and that a commercial application has an authorized signer. See [Entity Eligibility](/v2/products/entity/eligibility).

Your program can also require credit data on each account holder's and authorized signer's entity for approved applications. Your Technical Account Manager can tell you whether yours does. On an approved application, every update re-runs the entity checks, so a change to an entity since creation can fail an unrelated update.

## `details`

| **Field** | **Type** | **Description** |
| :- | :- | :- |
| `underwriting` | object | **Required.** See `details.underwriting`. |
| `adverse_action_notice` | object | **Required when `status` is `declined`.** See `details.adverse_action_notice`. |

### `details.underwriting`

| **Field** | **Type** | **Description** |
| :- | :- | :- |
| `is_secured` | boolean | **Required.** `true` if collateral secures the product. |
| `is_mla` | boolean | **Required.** `true` if the applicant is covered by the Military Lending Act. |
| `currency_code` | string | **Required.** ISO 4217 code, like `USD`. |
| `underwriting_grade` | string | Your internal underwriting grade. Any string. **Required when `status` is `approved` or `declined`.** |
| `limit` | integer | The credit limit assigned, in minor units. **Required when `status` is `approved`.** Cannot exceed `max_limit`. |
| `max_limit` | integer | The highest limit the applicant was approved for in original underwriting, in minor units. **Required when `status` is `approved`.** |
| `report` | object | Credit bureau data. Optional unless your program requires it. See `details.underwriting.report`. |

### `details.underwriting.report`

Optional unless your program requires it. Your Technical Account Manager can tell you whether yours does. When you send a report, `pulled_at` and `source` are required, and you send exactly one of `score` or `non_score_value`.

| **Field** | **Type** | **Description** |
| :- | :- | :- |
| `score` | integer | The bureau score, from 300 to 850. You cannot send it with `non_score_value`. |
| `non_score_value` | enum | `unestablished` or `frozen`, when the bureau returned no numeric score. You cannot send it with `score`. |
| `pulled_at` | timestamp | When you pulled the report. |
| `source` | enum | `equifax`, `experian`, or `transunion`. |

### `details.adverse_action_notice`

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

| **Field** | **Type** | **Description** |
| :- | :- | :- |
| `delivered_at` | timestamp | When you sent the notice to the applicant. |
| `reason` | string | The reason stated in the notice. |
| `delivery_method` | enum | `email`, `text`, or `other`. |

## `decision`

| **Field** | **Type** | **Description** |
| :- | :- | :- |
| `decided_at` | timestamp | **Required.** When you made the underwriting decision. |
| `reason` | string | **Required.** The reason for the decision. |
| `exception_approval_reason` | string | Send only when the decision was an exception to your underwriting criteria. The reason for approving outside your standard process. |

## `documents`

Each entry links a compliance document, like a disclosure, agreement, or consent, to the application. The document is a file you uploaded with the [Files API](/v2/products/files/overview). Upload the file with `POST /v2/files`, then send the returned `file_id` on the application.

You declare the document's type, like `truth_in_lending_document` or `consent_to_link_account`, when you upload the file. Each file has one type. Lead takes the type from the file, so document entries do not carry `type`, and the application does not return it. The file's type must be a compliance document type. The full list is on [The File Object](/v2/products/files/file-object#the-type-enum).

| **Field** | **Required** | **Description** |
| :- | :- | :- |
| `file_id` | Yes | A `file_` ID from the Files API. Lead checks that the file exists and belongs to your program. |
| `timestamp` | Yes | When your customer saw or agreed to the document, not when you uploaded the file. RFC 3339, UTC. It cannot be more than five minutes ahead of Lead's clock. |
| `version` | No | Your label for telling apart two documents of the same type on one application, like two versions of your terms. |

* **`documents` is required on create, and an empty array is valid.** Send `[]` when you have no documents to link yet, then add them later with a `PATCH`.
* **Each file appears at most once per application, and each file has one type.** If one document serves two types, upload it once for each. You can link several files of the same type, like two versions of your terms.
* **One file can back many applications.** Upload a static document like a fee schedule once and link it everywhere it applies.
* **A supplied array replaces the whole array.** To add a document, send every existing entry plus the new one. Lead re-checks every `file_id`.
* **When your customer accepts a new version, keep the old entry.** Add a new entry with its own `file_id`. A file never changes after upload, so a new version is a new file.

## Coming from the v0 Applications API

Applications keep their `id` across versions. An application you created on v0 is readable and updatable on v2, by `id` or `client_application_id`. v0 stays live until its sunset date, which Lead announces in [Upcoming Changes](/upcoming-changes) with sandbox time before you have to move.

Most fields carry over unchanged. These are the ones that differ:

| **v0 Applications API** | **Applications v2** | **What changed** |
| :- | :- | :- |
| `details.product_name` | `product_name` | Moved to the top level. |
| `details.credit` | `details.underwriting` | Renamed. Child fields are unchanged except `currency`. |
| `details.credit.currency` | `details.underwriting.currency_code` | Renamed. Same ISO 4217 values. |
| `documents[].document_id` | `documents[].file_id` | A Files API ID that Lead checks, in place of an SFTP filename. |
| `documents[].type` | The type of the linked file | You declare it on the file when you upload it. |
| `documents[].displayed_at`, `documents[].consented_at` | `documents[].timestamp` | One field for every document type. |
| None | `legacy_documents[]` | Read only. Document entries sent through v0. |
| v0 error responses | Lead error registry codes and payload | The same conditions fail. Codes and the payload shape follow the error registry. See [Errors](/api-reference/using-the-api/errors). |

* Document entries you sent through v0 come back in `legacy_documents`, exactly as you sent them. `documents` holds only the files you link on v2.
* `legacy_documents` is read only.

## Related

[Applications Overview](/v2/products/applications/overview) · [Application Statuses](/v2/products/applications/statuses) · [Entity Eligibility](/v2/products/entity/eligibility)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.