The Application Object

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

{
  "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.
`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`.
`details`	object	Underwriting and adverse action notice details. See `details`.
`decision`	object	When and why the decision was made. See `decision`.
`documents`	array	Compliance documents for the application, each referencing a file you uploaded. See `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. 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. 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.

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

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.

Applications Overview · Application Statuses · Entity Eligibility

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

Fields

`entities`

`details`

`details.underwriting`

`details.underwriting.report`

`details.adverse_action_notice`

`decision`

`documents`

Coming from the v0 Applications API

​Fields

​entities

​details

​details.underwriting

​details.underwriting.report

​details.adverse_action_notice

​decision

​documents

​Coming from the v0 Applications API

​Related

Fields

`entities`

`details`

`details.underwriting`

`details.underwriting.report`

`details.adverse_action_notice`

`decision`

`documents`

Coming from the v0 Applications API

Related