Introduction
The Accounts API reports your end-customer account data to Lead for compliance oversight. You use it to create accounts, update account details, and manage account status throughout the account lifecycle.
The API sits after Entity creation (and after Application creation for Lending use-casees) in the compliance onboarding sequence:
Entity API
Create entity records for each end customer. Lead validates KYC/KYB data at this step.
Applications API
Submit the terminal underwriting decision, referencing entity IDs from step 1. An approved application returns an application_id. Required for credit products only.
Accounts API
Create the account, referencing the application_id from step 2 (for credit products) or entity IDs directly (for deposit products).
active status. You can manage the account lifecycle through dedicated status-transition endpoints — activate, deactivate, and close.
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 Accounts API uses two OAuth scopes:
account/read_write — required for POST /v0/accounts, PATCH /v0/accounts/{id}, and all status-transition endpoints. Grants both read and write access.account/read — sufficient for GET /v0/accounts/{id}. Grants read-only access.
Use the least-privileged scope appropriate to your operation.
Endpoints
| Method | Path | Purpose |
|---|
POST | /v0/accounts | Create a new account. |
GET | /v0/accounts/{id} | Retrieve an account by ID. |
PATCH | /v0/accounts/{id} | Update mutable account properties. |
POST | /v0/accounts/{id}/activate | Transition an inactive account to active. |
POST | /v0/accounts/{id}/deactivate | Transition an active account to inactive. |
POST | /v0/accounts/{id}/close | Close an account (terminal). |
Attributes
Account Object
| Attribute | Type | Description |
|---|
| id | string | Unique identifier for the account. Prefixed with account_. |
| created_at | timestamp | Lead server-generated ISO 8601 timestamp when the account was created. |
| updated_at | timestamp | Lead server-generated ISO 8601 timestamp when the account was last updated. |
| application_id | string | Associated application ID, if any. Prefixed with application_. This is required when the credit_with_underwriting capability is present on the Account. |
| status | string | Current status of the account: active, inactive, or closed. |
| status_reason | string | Machine-readable reason for the current status. |
| capabilities | array | How the account is used: deposit, credit_with_underwriting, or credit_without_underwriting. Lead will validate necessary data requirement submission corresponding to each use-case, and this iniforms which types of Balances can be created referencing this account_id. |
| entities | object | Contains the derived account_holder_type (consumer or commercial). |
| details | object | Core account details including product name, credit information, and adverse action notice. See details object below. |
| documents | array | Compliance document references associated with the account. See documents array below. |
| metadata | object | Arbitrary key-value pairs for storing additional information. |
entities (object)
| Attribute | Type | Description |
|---|
| account_holder_type | string | Derived from the entity types of the account holders. consumer if all account holders are individuals; commercial if all are businesses or sole proprietors. |
details (object)
| Attribute | Type | Description |
|---|
| product_name | string | Your internal product name for the account. |
| closed_at | timestamp | ISO 8601 timestamp when the account was closed. Set by the /close endpoint. Read-only. |
| credit | object | Credit-specific details. Required when capabilities include credit_with_underwriting. See details.credit below. |
| adverse_action_notice | object | Adverse action notice details. Required when status_reason is client_closed. See details.adverse_action_notice below. |
details.credit (object)
| Attribute | Type | Description |
|---|
| is_secured | boolean | true if the product is secured (collateral attached); false otherwise. |
| is_mla | boolean | true if the account holder is subject to the Military Lending Act; false otherwise. |
| underwriting_grade | string | Your internal underwriting grade for the account holder. |
| currency | string | ISO 4217 currency code for the account (e.g., USD). |
| available_credit | integer | Available credit in minor units (e.g., cents). |
| limit | integer | Current credit limit in minor units. |
| max_limit | integer | Maximum credit limit approved in underwriting, in minor units. |
| scra | object | SCRA (Servicemembers Civil Relief Act) details. Optional. See details.credit.scra below. |
| report | object | Credit bureau report data. Optional. If included, all three sub-fields (score, pulled_at, source) are required. See details.credit.report below. |
details.credit.scra (object)
| Attribute | Type | Description |
|---|
| start_date | date | Start date for SCRA protections (YYYY-MM-DD). |
| end_date | date | End date for SCRA protections (YYYY-MM-DD). Optional. |
details.credit.report (object)
| Attribute | Type | Description |
|---|
| score | integer | Credit score returned by the bureau. Range: 300-850. |
| pulled_at | timestamp | ISO 8601 timestamp when the credit report was pulled. |
| source | string | Credit bureau that issued the report: equifax, experian, or transunion. |
details.adverse_action_notice (object)
| Attribute | Type | Description |
|---|
| delivered_at | timestamp | ISO 8601 timestamp when the adverse action notice was sent. |
| reason | string | The reason stated in the adverse action notice. |
| delivery_method | string | How the notice was delivered: email, text, or other. |
documents (array of objects)
| Attribute | Type | Description |
|---|
| document_id | string | Identifier for the document. |
| type | string | Document type (e.g., loan_agreement, esign_agreement). |
| consented_at | timestamp | ISO 8601 timestamp when the account holder consented. Present on consent documents. |
| displayed_at | timestamp | ISO 8601 timestamp when the document was displayed. Present on disclosure documents. |
Key Concepts
Account Capabilities
Every account declares one or more capabilities that inform Lead how the account is used. Capabilities determine which fields are required and which compliance validations apply. The three capabilities are:
deposit — a depository account (e.g., checking, savings).credit_with_underwriting — a credit account tied to an approved application. Requires application_id and the full details.credit object.credit_without_underwriting — a credit account that does not require underwriting (e.g., overdraft products). Does not require application_id or credit-specific fields.
Capabilities cannot be removed once added. If an account was created with incorrect capabilities, close it and create a new account.
Status Lifecycle
Accounts are created in active status. Status transitions are managed through dedicated endpoints — not by setting a status field on PATCH. The three states are:
active — the account is operational. Default on creation.inactive — the account is temporarily deactivated. Can be reactivated.closed — the account is permanently closed. This is a terminal state and cannot be undone.
Consumer vs. Commercial Accounts
The entities.account_holder_type field (consumer or commercial) is derived 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 account object; to see which entities are linked and in which role, use the entity relationships endpoint.
Entity Prerequisites
Entities must exist in Lead’s system before you can reference them in an account. Call the Entity API first to create entity records, then use the entity_-prefixed IDs in the entities.account_holders, entities.authorized_signers, and entities.authorized_users arrays of your account creation request.
Credit Accounts Require an Approved Application
For accounts with the credit_with_underwriting capability, the application_id field is required and must reference an application in approved status. Create the application through the Applications API before creating the account.
