The User Account Object

A user account is what you open at Lead for each of your customers. You create one with POST /v2/user_accounts, update it with PATCH /v2/user_accounts/{id}, and read it with GET /v2/user_accounts/{id}. POST and PATCH require an Idempotency-Key header of up to 255 characters. See Idempotency.

{
  "id": "user_account_2xYv6Kn3Jp7QuS2lY5mAbC0dE4f",
  "status": "active",
  "status_reason": "active",
  "application_id": "application_2xYv5Rt8Lm1NpQ4kW9zXcV7bH3j",
  "features": ["credit_with_underwriting"],
  "balance_sheet_model": "held_for_investment",
  "product_config_id": "product_config_2xYv4Hs2Dk6MfT8rP1qLnB5wE9a",
  "product_name": "Everyday Card",
  "entities": {
    "account_holder_type": "consumer",
    "account_holders": ["entity_2xYv3Gq7Cj5LeS1oN6mKaA4vD8z"],
    "authorized_signers": [],
    "authorized_users": []
  },
  "details": {
    "underwriting": {
      "is_secured": false,
      "is_mla": false,
      "underwriting_grade": "A",
      "currency_code": "USD",
      "available_credit": 150000,
      "limit": 150000,
      "max_limit": 250000,
      "report": {
        "pulled_at": "2026-03-01T09:45:00Z",
        "source": "experian",
        "score": 720
      }
    }
  },
  "documents": [
    { "file_id": "file_7RwQ2mK9pL4xT1vN8jS5", "timestamp": "2026-03-01T09:58:00Z", "version": "v1" }
  ],
  "metadata": {},
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z",
  "closed_at": null
}

Fields

Field	Type	Description
`id`	string	Unique identifier, prefixed `user_account_`.
`status`	enum	`active`, `inactive`, or `closed`. See User Account Statuses.
`status_reason`	enum	Why the user account is in its current status. See Status reasons on User Account Statuses.
`application_id`	string	The approved application behind the user account. Required when `features` includes `credit_with_underwriting`.
`features`	array of enums	How the user account is used: `deposit`, `credit_with_underwriting`, `credit_without_underwriting`. You set them through `requested_features`. See Features.
`balance_sheet_model`	enum or null	`held_for_investment` or `held_for_sale`. Required when the user account has a credit feature. `null` means the user account has no credit feature. See Balance sheet model.
`product_config_id`	string or null	The product config the user account was created under, prefixed `product_config_`. Required on create and cannot be changed. `null` only on user accounts created before product configs existed. See Product config.
`product_name`	string	Your internal name for the product, for example “Everyday Checking”.
`entities`	object	Who holds the user account. See The entities block.
`details`	object	Underwriting data and the adverse action notice. See The details block.
`documents`	array	Compliance documents for the user account, like agreements, disclosures, and consents. Each entry references a file you uploaded with the Files API. Required on create, and `[]` is valid. See Documents.
`legacy_documents`	array	Response only. Document entries sent through v0, on user accounts created on v0. Read only. See Documents.
`metadata`	object	Key-value pairs for your own use. Lead does not read them.
`client_account_id`	string	Read-only. The identifier you assigned in an Account file. Present only on user accounts created through file upload. Omitted on user accounts created through the API, which are identified only by `id`.
`created_at`, `updated_at`	timestamp	RFC 3339, UTC.
`closed_at`	timestamp or null	When the user account was closed. Set by Lead when you call `/close`.

Features

You set features with requested_features on create. The user account returns what it was granted as features. Each feature has its own set of required fields, and Lead checks them when you create the user account.

deposit. The user account holds deposits, such as checking or savings.
credit_with_underwriting. The user account extends credit backed by an approved application. Requires application_id, details.underwriting, and balance_sheet_model. At least one account holder must be eligible for account_holder. A minor account holder can be on the user account, but not as its only holder.
credit_without_underwriting. The user account extends credit with no underwriting decision behind it, such as a courtesy overdraft draw. Requires balance_sheet_model. Does not require application_id or details.underwriting.

Your program allows a pre-approved set of features. If you request one it does not allow, Lead returns a 422. Ask your Technical Account Manager to enable additional features if you believe you are seeing a 422 in error. You can add features with PATCH, but you cannot remove them. When you patch requested_features, send the full list, not only the new values.

Balance sheet model

balance_sheet_model records how Lead carries the user account’s credit on its balance sheet:

held_for_investment. Lead intends to hold any loan receivables belonging to this user account for the foreseeable future.
held_for_sale. Any loan receivables belonging to this user account are earmarked to be sold.

Send it on create whenever requested_features includes a credit feature. Leave it out on deposit-only user accounts. Lead checks the value against the models your program allows, even if your program allows only one. You cannot change balance_sheet_model after creation. Lead may change it from held_for_investment to held_for_sale if the user account is tagged such that all future loan receivables created should be earmarked to be sold.

Product config

product_config_id identifies the product configuration your Lead team set up for your program. Your Technical Account Manager gives you the ID. Send it on every create request. Lead checks that it exists and belongs to your program. You cannot change product_config_id after creation. User accounts created before product configs existed return null.

You cannot retrieve a product config yet. Store the ID your Technical Account Manager gives you. A retrievable Product Config object is planned, and the IDs you send today will keep working when it ships.

The entities block

Field	Type	Description
`account_holder_type`	enum	`consumer` or `commercial`. Response only. Lead derives it from the account holders. See below.
`account_holders`	array	Entity IDs of the account holders. At least 1, at most 20. If your program is approved for minor account holders, include them here too.
`authorized_signers`	array	Entity IDs of authorized signers. At most 20. At least 1 is required on a commercial user account.
`authorized_users`	array	Entity IDs of authorized users. At most 20.

Lead sets account_holder_type from the entities you list as account holders:

Individuals produce consumer.
Businesses and sole proprietors produce commercial. You can combine the two on one user account.
You cannot mix individuals with businesses or sole proprietors as account holders.

Every entity must already exist and must be eligible for the relationship type you give it: account_holder or minor_account_holder for entities in account_holders, authorized_signer for authorized_signers, and authorized_user for authorized_users. minor_account_holder applies only if your program is approved for minor account holders. Create entities with the Entity API first, and check eligibility on the entity before you reference it. See Entity Eligibility. When the user account references an application, its account holder type must match the application’s. Its account holders and authorized signers must also match the application’s when you create the user account. After that, you can change them through the entity relationships endpoints.

The details block

Field	Type	Description
`underwriting`	object	Underwriting data for the user account. Required when `features` includes `credit_with_underwriting`.
`adverse_action_notice`	object	The adverse action notice you sent the account holder. Required when you close the user account with `status_reason` `client_closed`.

details.underwriting

Field	Type	Description
`is_secured`	boolean	`true` if collateral secures the credit. Required.
`is_mla`	boolean	`true` if the account holder is covered by the Military Lending Act. Required.
`underwriting_grade`	string	Your internal underwriting grade. Required.
`currency_code`	string	ISO 4217 currency code, for example `USD`. Required.
`available_credit`	integer	Available credit in minor units. Required.
`limit`	integer	Current credit limit in minor units. Required.
`max_limit`	integer	Maximum limit approved in underwriting, in minor units. Required.
`scra`	object	Servicemembers Civil Relief Act protection dates. Optional. `start_date` is required when present, and `end_date` is optional. Both are `YYYY-MM-DD`.
`report`	object	Credit bureau report. Optional unless your program requires it. Your Technical Account Manager can tell you whether yours does. See below.

If you send report, include pulled_at and source, plus exactly one of score or non_score_value:

Field	Type	Description
`pulled_at`	timestamp	When the report was pulled.
`source`	enum	`equifax`, `experian`, or `transunion`.
`score`	integer	Bureau score, 300 to 850.
`non_score_value`	enum	`unestablished` or `frozen`, when the bureau returned no score.

details.adverse_action_notice

Send all three fields or none.

Field	Type	Description
`delivered_at`	timestamp	When you sent the notice.
`reason`	string	The reason stated in the notice.
`delivery_method`	enum	`email`, `text`, or `other`.

Documents

Each entry in documents links a compliance document, like an agreement, disclosure, or consent, to the user account. The document is a file you uploaded with the Files API. Upload the file with POST /v2/files, declaring its type, then link the returned file_id on the user account. Each file has one type, which you declare when you upload it. Lead takes the type from the file, so document entries do not carry type, and the user account does not return it. Retrieve it with GET /v2/files/{id}. The file’s type must be one of the compliance document types that the user account accepts. The full list is in The type enum. Each entry has these fields:

file_id (required). A file_ ID from the Files API. Lead checks that the file exists and belongs to your program.
timestamp (required). When your customer was shown or agreed to the document, not when you uploaded the file. RFC 3339, UTC. It can’t be more than 5 minutes ahead of Lead’s clock.
version (optional). Your label for telling apart two documents of the same type on one user account, like two versions of your terms.

Things to know when you link files:

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 user account. If one document serves two types, upload it once for each type. You can link several files of the same type, like two versions of your terms.
One file can back many user accounts. 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 and add a new one with its own file_id. A file never changes after upload, so a new version is a new file.
A request that breaks one of these rules returns 422 parameters_invalid naming the entry.

User accounts created on v0

When you read a user account created on v0 through v2, the document entries you sent through v0 come back in legacy_documents, exactly as you sent them, including document_id, type, displayed_at or consented_at, and version. documents holds only the files you link on v2. legacy_documents is read only. If a POST or PATCH includes it, Lead ignores it and returns no error.

Coming from the v0 Accounts API

Most fields carry over unchanged. These are the ones that differ:

Accounts API	User Accounts API	What changed
`id` (`account_…`)	`id` (`user_account_…`)	New prefix. Existing objects keep the same ID suffix, so `account_abc` becomes `user_account_abc`.
`capabilities`	`features` (response), `requested_features` (request)	Renamed. Values are the same.
`details.product_name`	`product_name`	Moved to the top level.
`details.closed_at`	`closed_at`	Moved to the top level.
`details.credit`	`details.underwriting`	Renamed. Sub-fields are the same except currency.
`details.credit.currency`	`details.underwriting.currency_code`	Renamed.
`entities` (response)	`entities` (response)	Now returns `account_holders`, `authorized_signers`, and `authorized_users` alongside `account_holder_type`.
—	`balance_sheet_model`	New. Lead fills it on existing user accounts with a credit feature, from your program’s configuration, and is now required on User Account creates.
—	`product_config_id`	New. `null` on existing user accounts.
`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	Declared on the file when you upload it. Not returned on the user account.
`documents[].displayed_at`, `documents[].consented_at`	`documents[].timestamp`	One field for every document type.
—	`legacy_documents`	New. Read only. Holds the document entries you sent through v0, exactly as you sent them.

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

Fields

Features

Balance sheet model

Product config

The entities block

The details block

details.underwriting

details.adverse_action_notice

Documents

User accounts created on v0

Coming from the v0 Accounts API

​Fields

​Features

​Balance sheet model

​Product config

​The entities block

​The details block

​details.underwriting

​details.adverse_action_notice

​Documents

​User accounts created on v0

​Coming from the v0 Accounts API

​Related

Fields

Features

Balance sheet model

Product config

The entities block

The details block

details.underwriting

details.adverse_action_notice

Documents

User accounts created on v0

Coming from the v0 Accounts API

Related