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

# User Accounts: What You Open for Each Customer

> What a user account is, how features and product configs shape it, and how it relates to entities, applications, user credit and deposit balances, and cards.

A user account is what you open at Lead for each of your customers. It records who holds the user account, what it is used for, and the compliance data Lead needs to oversee it. You create user accounts, update them, and manage their status through the User Accounts API.

A user account does not hold money itself. User credit balances and user deposit balances are separate resources that sit beneath it and reference its `user_account_id`.

The bank accounts your program runs on, such as your FBO and operating accounts, are core accounts and are documented under [Core Account](/products/core-account/overview).

The creation of a user account for your end-user first happens in your system, and the user account record is how you communicate the terms of the product offered to your end-user to Lead. See [Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting).

<Note>
  The User Accounts API is currently in preview with a planned beta release in December 2026. Preview APIs are not yet available in sandbox or production and can change before beta. Use these pages to plan an integration, not to build one. Once released in beta, it will be available to all partners in sandbox, and in production for select programs. Beta APIs may change without a version increment, and changes will be announced in advance. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility).
</Note>

## Features

Every user account has one or more features that tell Lead how the user account is going to be used: `deposit`, `credit_with_underwriting`, or `credit_without_underwriting`. You ask for them in `requested_features` when you create the user account, and the user account returns them as `features`.

* If you intend to create User Deposit Balances under the user account, the `deposit` feature must be requested.
* If you intend to create User Credit Balances under the user account and your product has an explicit underwriting process where the end-user can be rejected (e.g., a business loan, a personal credit card), then request `credit_with_underwriting`.
* If you intend to create User Credit Balances under the user account and your product does not have an explicit underwriting process where the end-user can be rejected (e.g., courtesy overdraft), then request `credit_without_underwriting`.

Features set which fields are required and which compliance checks Lead runs. They also set which user credit balances and user deposit balances you can create under the user account. **You can add features later, but you cannot remove them.** [The User Account Object](/v2/products/user-accounts/user-account-object#features) page explains what each feature requires.

## Product config and balance sheet model

Two fields are new on the user account:

* **`product_config_id`** is required on every create request. It identifies the product configuration your Lead team set up for your program. Your Technical Account Manager gives you the ID. You cannot change it after creation.
* **`balance_sheet_model`** is required when the user account has a credit feature: `held_for_investment` or `held_for_sale`. Lead checks it against the models your program allows. It is `null` on deposit-only user accounts.

## Who holds a user account

Each user account lists its account holders, authorized signers, and authorized users by entity ID. Lead derives `account_holder_type` from the holders: `consumer` for individuals, `commercial` for businesses and sole proprietors. Commercial user accounts need at least one authorized signer. [The User Account Object](/v2/products/user-accounts/user-account-object#the-entities-block) page documents more on this in the entities block.

## Where it fits in onboarding

A user account can be created after its entities exist. For underwritten credit products, it can be created after the application is approved. Before your first `POST` request, get your `product_config_id` from your Technical Account Manager. Every `POST` request requires it. You cannot look it up through the API for now, but a Product Configuration API is planned. Here is the typical path you'll follow:

<Steps>
  <Step title="Entity API">
    Create an entity for each account holder, authorized signer, and authorized user of a product that you are creating. Successful `POST`s return an `entity_id`.
  </Step>

  <Step title="Applications API">
    For underwritten credit products only. Report the final underwriting decision to inform Lead of the outcome. Successful `POST`s return an `application_id`.
  </Step>

  <Step title="User Accounts API">
    Create the user account. Reference the entity IDs, plus the `application_id` if the user account you are creating has the `credit_with_underwriting` feature.
  </Step>
</Steps>

## How user accounts relate to the rest of the model

* **Entities.** Every person or business on the user account is an entity. Create entities first before attempting to create a user account.
* **Applications.** A user account with the `credit_with_underwriting` feature requires an approved application.
* **User credit balances.** User credit balances sit beneath the user account and reference a `user_account_id`.
* **User deposit balances.** User deposit balances sit beneath the user account and reference a `user_account_id`.
* **Cards.** Cards reference the user account by `user_account_id`.

## What you can do

* `POST /v2/user_accounts`: Create a user account.
* `GET /v2/user_accounts/{id}`: Retrieve a user account.
* `GET /v2/user_accounts?client_account_id={client_account_id}`: Retrieve a user account by the `client_account_id` you assigned in an Account file. Use this to find the `user_account_id` for user accounts you created through Account files if you are moving to the API from files.
* `PATCH /v2/user_accounts/{id}`: Update a set of allowable fields.
* `POST /v2/user_accounts/{id}/activate`: Update the status of a user account to `active`.
* `POST /v2/user_accounts/{id}/deactivate`: Update the status of a user account to `inactive`.
* `POST /v2/user_accounts/{id}/close`: Close a user account.
* `GET /v2/user_accounts/{id}/entity_relationships`: List the entities linked to a user account and their relationship types.
* `POST /v2/user_accounts/{id}/entity_relationships/batch`: Add entities to a user account.
* `DELETE /v2/user_accounts/{id}/entity_relationships/{entity_id}`: Remove an entity from a user account.

### Authentication

* **`user_account/read_write`** for create, update, status changes, and adding or removing entities. Also grants read access.
* **`user_account/read`** for the `GET` endpoints only. Use it when your integration only needs to read user accounts.

## What you cannot do

* **Mix old and new objects.** User Accounts are designed to be adopted together with User Credit Balances, and with User Deposit Balances and Cards once they are available. Your Lead team will coordinate your move.
* **Remove a feature.** Features only grow. If a user account was opened with the wrong feature, close it and open a new one.
* **Change `product_config_id` or `balance_sheet_model`.** Both are set at creation. Lead may update `balance_sheet_model` if required by the terms of your program.
* **Change status with `PATCH`.** Use the activate, deactivate, and close endpoints. See [User Account Statuses](/v2/products/user-accounts/statuses).
* **Subscribe to User Account webhooks.** There are no User Account webhook events. Your system sets every status, so read the User Account with `GET` when you need it.

## In this section

* [The User Account Object](/v2/products/user-accounts/user-account-object)
* [User Account Statuses](/v2/products/user-accounts/statuses)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.