Introduction
The Applications API must be used for any lending or credit product built on Lead. When your underwriting process reaches a final outcome — approved, declined, or canceled — you submit that decision here. Lead uses this data to satisfy Reg B and fair lending obligations, and the resultingapplication_id is required to create Accounts for lending and credit use-cases downstream.
The API sits between the Entity API and the Accounts API in the onboarding sequence:
Applications API
Submit the underwriting outcome, referencing the entity IDs from step 1. An approved application returns an
application_id.POST /v0/applications request represents a final underwriting decision. All three outcomes (approved, declined, and canceled) must be reported; declined and canceled applications are required for fair lending compliance even though no account is created for them.
A separate OpenAPI spec covers the full schema definition for request and response bodies. This page provides conceptual context for integrating with the API.
Authentication
The Applications API uses two OAuth scopes:application/read_write— required forPOST /v0/applications. Grants both read and write access.application/read— sufficient forGET /v0/applications/{id}andGET /v0/applications/{id}/entity_relationships. Grants read-only access.
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /v0/applications | Create a new application in a terminal state (approved, declined, or canceled). |
GET | /v0/applications/{id} | Retrieve a specific application by ID. |
GET | /v0/applications/{id}/entity_relationships | List all account holders and authorized signers linked to an application. |
Application Object
| Attribute | Type | Description |
|---|---|---|
| id | string | Unique identifier for the application. Prefixed with application_. |
| 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. Possible values: approved, declined, canceled. |
| entities | object | Contains information about the account holder and authorized signers. See entities object below. |
| details | object | Contains product, credit, and adverse action notice details. See details object below. |
| decision | object | Contains information about the underwriting decision. See decision object below. |
| documents | array | Document references associated with the application. See documents array below. |
| metadata | object | Arbitrary key-value pairs for storing additional information. |
entities (sub-object)
| Attribute | Type | Description |
|---|---|---|
| account_holder_type | string | Denotes whether the application is for a consumer or commercial account. consumer if all account holders are individuals; commercial if all account holders are businesses or sole proprietors. |
details (sub-object)
| Attribute | Type | Description |
|---|---|---|
| product_name | string | Your internal product name. This tells Lead’s Due Diligence team which product this application, if approved, would open an account for. |
| credit | object | Credit-specific properties for the application. See details.credit object below. |
| adverse_action_notice | object | Adverse action notice details. Required when status is declined. See details.adverse_action_notice object below. |
details.credit (sub-object)
| Attribute | Type | Description |
|---|---|---|
| is_secured | boolean | Indicates if this is a secured credit/deposit product. true if the product is secured (collateral attached); false otherwise. |
| is_mla | boolean | true if the applicant is subject to the Military Lending Act; false otherwise. |
| currency | string | ISO 4217 currency code for the application (e.g., USD). |
| underwriting_grade | string | Your internal underwriting grade for the applicant. Accepts any string mapped to your specific scoring framework. |
| limit | integer | The credit limit assigned to the applicant, in minor units (e.g., cents). |
| max_limit | integer | The maximum credit limit the applicant was approved for based on original underwriting, in minor units (e.g., cents). |
| report | object | Credit bureau report data. Optional. If included, all three sub-fields (score, pulled_at, source) are required. See details.credit.report object below. |
details.credit.report (sub-object)
| Attribute | Type | Description |
|---|---|---|
| score | integer | Credit score returned by the bureau. Supported range is 300-850. |
| pulled_at | timestamp | ISO 8601 timestamp when the credit report was pulled. |
| source | string | Credit bureau that issued the report. Possible values: equifax, experian, transunion. |
details.adverse_action_notice (sub-object)
| 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 to the applicant. Possible values: email, text, other. |
decision (sub-object)
| Attribute | Type | Description |
|---|---|---|
| decided_at | timestamp | ISO 8601 timestamp when the underwriting decision was made. |
| reason | string | The reason for the decision. |
| exception_approval_reason | string | This should only be provided if the decision was made as an exception to underwriting criteria. Reason for exception approval, if this decision was made as an exception to the traditional underwriting process. |
documents (array of objects)
| Attribute | Type | Description |
|---|---|---|
| document_id | string | Identifier for the document. |
| type | string | Document type (e.g., credit_check_consent, adverse_action_notice, business_license). |
| consented_at | timestamp | ISO 8601 timestamp when the applicant consented to the document. Present on consent documents. |
| displayed_at | timestamp | ISO 8601 timestamp when the document was displayed to the applicant. Present on disclosure documents. |
Key Concepts
Terminal-only Status Model Applications are created already in a final state:approved, declined, or canceled. There is no in-progress state. You must know the underwriting outcome before calling POST /v0/applications. If a status was reported incorrectly, it can be corrected through the API.
Consumer vs. Commercial Account Holder Types
The entities.account_holder_type field in the response (consumer or commercial) is derived automatically from the entity types you supply — it is not set directly. Individual entities produce consumer; business or sole proprietor entities produce commercial. The underlying entity ID lists are not returned on the application object; to see which entities are linked in which role, call GET /v0/applications/{id}/entity_relationships.
Entity Prerequisites
Entities must exist in Lead’s system before you can reference them in an application. Call the Entity API first to create entity records, then use the entity_-prefixed IDs returned from that API in the entities.account_holders and entities.authorized_signers arrays of your application request.