> ## 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.
# Accounts API Overview
> Report deposit and credit account data to Lead using the Accounts API, including creation, status transitions, OAuth scopes, and lifecycle management.
## Introduction
The [Accounts API](/api-reference/endpoint/account/create-an-account) 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-cases) in the compliance onboarding sequence:
Create entity records for each end customer. Lead validates KYC/KYB data at this step.
Submit the terminal underwriting decision, referencing entity IDs from step 1. An approved application returns an `application_id`. Required for credit products only.
Create the account, referencing the `application_id` from step 2 (for credit products) or entity IDs directly (for deposit products).
Accounts are created in `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 informs 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`. 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 account. 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.