> ## 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. # The User Account Object > Field-level reference for the User Account object, including features, product config, balance sheet model, entities, underwriting details, and the mapping from the Accounts API. 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](/api-reference/using-the-api/idempotency). ```json theme={null} { "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](/v2/products/user-accounts/statuses). | | `status_reason` | enum | Why the user account is in its current status. See [Status reasons](/v2/products/user-accounts/statuses#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](#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](#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-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](#the-entities-block). | | `details` | object | Underwriting data and the adverse action notice. See [The details block](#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](/v2/products/files/overview). Required on create, and `[]` is valid. See [Documents](#documents). | | `legacy_documents` | array | Response only. Document entries sent through v0, on user accounts created on v0. Read only. See [Documents](#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](/products/entity/roles#validating-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](/v2/products/files/overview). 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](/v2/products/files/file-object#the-type-enum). Each entry has these fields: * **`file_id`** (required). A `file_` ID from the [Files API](/v2/products/files/overview). 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. | ## Related * [User Account Overview](/v2/products/user-accounts/overview) * [User Account Statuses](/v2/products/user-accounts/statuses) * [Entity](/products/entity/overview) * [Applications](/products/applications/overview) * [The Core Account Object](/products/core-account/core-account-object) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.