Applications API Overview

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 resulting application_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:

Entity API

Create entity records for each applicant. Lead validates KYC/KYB data at this step.

Applications API

Submit the underwriting outcome, referencing the entity IDs from step 1. An approved application returns an application_id.

Accounts API

Create the account for the credit or lending product, referencing the application_id from step 2.

Applications are always submitted in a terminal state — there is no in-progress state. Every 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 for POST /v0/applications. Grants both read and write access.
application/read — sufficient for GET /v0/applications/{id} and GET /v0/applications/{id}/entity_relationships. Grants read-only access.

Use the least-privileged scope appropriate to your operation.

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. Required when `status` is `approved` or `declined` for credit products.
limit	integer	The credit limit assigned to the applicant, in minor units (e.g., cents). Required when `status` is `approved` for credit products.
max_limit	integer	The maximum credit limit the applicant was approved for based on original underwriting, in minor units (e.g., cents). Required when `status` is `approved` for credit products.
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. All entries in account_holders must share the same category — every entry an individual, or every entry a business or sole proprietor. Mixing an individual entity with a business or sole proprietor entity is not permitted, but business and sole proprietor entities may be combined within the same application. 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.

Foundations

API Guides

Introduction

Authentication

Endpoints

Application Object

entities (sub-object)

details (sub-object)

details.credit (sub-object)

details.credit.report (sub-object)

details.adverse_action_notice (sub-object)

decision (sub-object)

documents (array of objects)

Key Concepts

​Introduction

​Authentication

​Endpoints

​Application Object

​entities (sub-object)

​details (sub-object)

​details.credit (sub-object)

​details.credit.report (sub-object)

​details.adverse_action_notice (sub-object)

​decision (sub-object)

​documents (array of objects)

​Key Concepts

Introduction

Authentication

Endpoints

Application Object

entities (sub-object)

details (sub-object)

details.credit (sub-object)

details.credit.report (sub-object)

details.adverse_action_notice (sub-object)

decision (sub-object)

documents (array of objects)

Key Concepts