---
title: "Create a user account"
method: POST
path: "/v2/user_accounts"
tags: ["User Account"]
---

# Create a user account

`POST /v2/user_accounts`

## Request

- Base URL: `https://api.sandbox.lead.bank`
- URL: `https://api.sandbox.lead.bank/v2/user_accounts`
- Auth: HTTP bearer

Create a User Account.

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateUserAccountRequestV2: Request body for creating a new user account
  - `application_id` string: Unique identifier for the application. Prefixed with `application_`.
  - `requested_features` UserAccountFeatureV2[], required: The features the user account should be granted. The feature must be pre-approved for your program. Learn more about features [here](/v2/products/user-accounts/user-account-object#features).
  - `entities` CreateUserAccountEntitiesV2, required: Entity relationships for the user account (POST request only). Maximum 20 entities per relationship type. Cannot mix individual and business/sole_prop entities in account_holders. Authorized signers required for business/sole_prop account holders.
    - `account_holders` EntityID[], required: Account holders (min 1, max 20)
    - `authorized_signers` EntityID[]: Authorized signers on the user account (required with min 1 if business/sole_prop account holders)
    - `authorized_users` EntityID[]: Authorized users on the user account
  - `product_name` string, required: Partner's name for their product
  - `balance_sheet_model` 'held_for_investment' | 'held_for_sale': How Lead carries the user account's credit on its balance sheet.
  - `product_config_id` string, required: Identifies the product configuration set up for your program. Provided to you by your Lead Technical Account Manager. Cannot be changed once set.
  - `details` object: Additional details for the user account
    - `underwriting` CreateUserAccountUnderwritingV2: Underwriting details for creating a user account. All fields are required except `scra` and `report`.
      - `is_secured` boolean, required: Indicates if this is a secured credit/deposit product
      - `is_mla` boolean, required: Indicates if this user account is considered a Military Lending Act account
      - `underwriting_grade` string, required: Grade given to the customer based on underwriting
      - `currency_code` string, required: The currency for the user account (3-letter ISO code)
      - `available_credit` integer, required: Available credit for the customer to draw (in minor units)
      - `limit` integer, required: Current credit limit (in minor units)
      - `max_limit` integer, required: Maximum credit limit approved in underwriting (in minor units)
      - `scra` Scra: SCRA (Servicemembers Civil Relief Act) details
        - `start_date` string, date, required: Start date for SCRA protections
        - `end_date` string, date: End date for SCRA protections
      - `report` CreditReport: Credit report information. Exactly one of `score` or `non_score_value` must be provided; `pulled_at` and `source` are always required when a credit report is supplied.
        - `score` integer: Credit score returned by the bureau. Supported range is 300-850. Mutually exclusive with `non_score_value`.
        - `non_score_value` 'unestablished' | 'frozen': Indicates the state of a credit file when a numeric score is not available. Mutually exclusive with `score`.
        - `pulled_at` string, date-time, required: ISO 8601 timestamp when the credit report was pulled.
        - `source` 'equifax' | 'transunion' | 'experian', required: Credit bureau that issued the report. Possible values: `equifax`, `experian`, `transunion`.
    - `adverse_action_notice` AdverseActionNotice: Adverse action notice information
      - `delivered_at` string, date-time, required: ISO 8601 timestamp when the adverse action notice was sent to the applicant.
      - `reason` string, required: The reason stated in the adverse action notice.
      - `delivery_method` 'email' | 'text' | 'other', required: How the notice was delivered to the applicant. Possible values: `email`, `text`, `other`.
  - `metadata` Metadata: A set of key-value pairs that can be used to store additional information related to this object.
  - `documents` FileDocument[], required: Legal or informational documents associated with the user account, each referencing a file you uploaded with `POST /v2/files`. Lead accepts only files whose type can link to a user account. See the [file type enum list](https://docs.lead.bank/v2/products/files/file-object#the-type-enum). A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Send `[]` when you have no documents to link yet.
    - `file_id` string, required: Lead-issued identifier of the file, from `POST /v2/files`.
    - `timestamp` string, date-time, required: When the end-user was shown or agreed to the document, per the file type. Partner-supplied; records an exchange between the partner and end-user, never upload time. ISO 8601, UTC.
    - `version` string: Partner-supplied label used for static documents so that two entries of the same type on one object can be ordered (e.g. terms of use v1 and v2).

## Response `200`

User account created successfully.

- UserAccountV2: A user account object
  - `id` string, required: The ID of the User Account object.
  - `status` 'active' | 'inactive' | 'closed', required: Current state of the user account
  - `status_reason` 'client_closed' | 'entity_closed' | 'frozen' | 'dormant' | 'active' | 'paid_off' | 'charged_off' | 'canceled' | 'other', required: Machine-readable reason for the current status
  - `application_id` string: Unique identifier for the application. Prefixed with `application_`.
  - `features` UserAccountFeatureV2[], required: Features granted to the user account.
  - `entities` UserAccountEntitiesV2, required: Entity relationships associated with the user account (response only)
    - `account_holder_type` 'consumer' | 'commercial': Derived from the type of the entity referenced in account_holders
  - `details` UserAccountDetailsV2, required: Core details of the user account
    - `underwriting` UserAccountUnderwritingV2: Underwriting details for the user account
      - `is_secured` boolean: Indicates if this is a secured credit/deposit product
      - `is_mla` boolean: Indicates if this user account is considered a Military Lending Act account
      - `underwriting_grade` string: Grade given to the customer based on underwriting
      - `currency_code` string: The currency for the user account (3-letter ISO code)
      - `available_credit` integer: Available credit for the customer to draw (in minor units)
      - `limit` integer: Current credit limit (in minor units)
      - `max_limit` integer: Maximum credit limit approved in underwriting (in minor units)
      - `scra` Scra: SCRA (Servicemembers Civil Relief Act) details
        - `start_date` string, date, required: Start date for SCRA protections
        - `end_date` string, date: End date for SCRA protections
      - `report` CreditReport: Credit report information. Exactly one of `score` or `non_score_value` must be provided; `pulled_at` and `source` are always required when a credit report is supplied.
        - `score` integer: Credit score returned by the bureau. Supported range is 300-850. Mutually exclusive with `non_score_value`.
        - `non_score_value` 'unestablished' | 'frozen': Indicates the state of a credit file when a numeric score is not available. Mutually exclusive with `score`.
        - `pulled_at` string, date-time, required: ISO 8601 timestamp when the credit report was pulled.
        - `source` 'equifax' | 'transunion' | 'experian', required: Credit bureau that issued the report. Possible values: `equifax`, `experian`, `transunion`.
    - `adverse_action_notice` AdverseActionNotice: Adverse action notice information
      - `delivered_at` string, date-time, required: ISO 8601 timestamp when the adverse action notice was sent to the applicant.
      - `reason` string, required: The reason stated in the adverse action notice.
      - `delivery_method` 'email' | 'text' | 'other', required: How the notice was delivered to the applicant. Possible values: `email`, `text`, `other`.
  - `product_name` string, required: Partner's name for their product
  - `documents` FileDocument[], required: Legal or informational documents associated with the user account, each referencing a file you uploaded with `POST /v2/files`. Lead accepts only files whose type can link to a user account. See the [file type enum list](https://docs.lead.bank/v2/products/files/file-object#the-type-enum).
    - `file_id` string, required: Lead-issued identifier of the file, from `POST /v2/files`.
    - `timestamp` string, date-time, required: When the end-user was shown or agreed to the document, per the file type. Partner-supplied; records an exchange between the partner and end-user, never upload time. ISO 8601, UTC.
    - `version` string: Partner-supplied label used for static documents so that two entries of the same type on one object can be ordered (e.g. terms of use v1 and v2).
  - `legacy_documents` LegacyUserAccountDocumentV2[]: Document entries created on v0 User Accounts, returned exactly as sent. Read only: ignored if included on a POST or PATCH.
    - `document_id` string: The SFTP filename sent on v0 as the document reference. Lead did not check that the file arrived.
    - `type` 'aan' | 'loan_agreement' | 'loc_agreement' | 'truth_in_lending_document' | 'ach_authorization' | 'notice_of_incompleteness' | 'credit_score_notice' | 'offer_summary' | 'personal_guarantee' | 'consumer_credit_auth' | 'partner_privacy_policy' | 'lead_privacy_policy' | 'terms_of_use' | 'esign_agreement' | 'credit_pull_consent' | 'fcra_notice' | 'tcpa_consent' | 'patriot_act_notice' | 'mla_notice' | 'pre_approval_terms' | 'eft_authorization' | 'prohibited_industry_certification' | 'decision_maker_document' | 'bo_certification' | 'missed_payments_policy' | 'consent_to_link_account' | 'consent_to_link_hsa' | 'negative_option_consent' | 'lead_funds_transfer_agreement' | 'deposit_agreement' | 'cardholder_agreement' | 'periodic_statement' | 'autopay_authorization': Type of document associated with an application
    - `displayed_at` string, date-time: When the document was shown to the account holder, as sent on v0. Present on disclosure documents.
    - `consented_at` string, date-time: When the account holder consented to the document, as sent on v0. Present on consent documents.
    - `version` string: The version label sent on v0.
  - `client_account_id` string: 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`.
  - `balance_sheet_model` 'held_for_investment' | 'held_for_sale': How Lead carries the user account's credit on its balance sheet.
  - `product_config_id` string, nullable: The id of the product configuration the user account was created under. `null` only on user accounts created before product config ids existed.
  - `metadata` Metadata, required: A set of key-value pairs that can be used to store additional information related to this object.
  - `created_at` string, date-time, required: Creation timestamp
  - `updated_at` string, date-time, required: Last update timestamp
  - `closed_at` string, date-time, nullable: Timestamp when the user account was closed. Updated by /close endpoint.

## Other responses

- `400`: The request could not be parsed (`request_malformed`), or the `Idempotency-Key` header is missing (`idempotency_key_missing`).
- `403`: `code` is one of: `authentication_missing` (the request has no credentials), `token_invalid` (the bearer token is missing, expired, or invalid, or does not grant `user_account/read_write`), `source_ip_not_permitted` (the request came from an IP address that is not on your program's allowlist).
- `409`: A concurrent request with the same `Idempotency-Key` is still in flight.
- `413`: The request body is over this endpoint's size limit, for example because `metadata` is too large (`content_too_large`; `errors[].code` is `body_too_large`).
- `422`: The request was parsed but cannot be processed. `code` is one of: `parameters_invalid` (a field is missing or invalid; a feature-dependent field is missing, like `balance_sheet_model` when `requested_features` includes a credit feature, or `application_id` and `details.underwriting` for `credit_with_underwriting` (`dependent_parameter_required`); `limit` exceeds `max_limit` (`parameter_bound_exceeded`); a `documents[].file_id` appears twice, or an entity appears twice in one relationship type (`parameter_duplicated`); or a `documents[].timestamp` is more than five minutes in the future (`future_date_not_permitted`). All failures are returned at once), `related_object_invalid` (an entity, the `application_id`, the `product_config_id` or a `documents[].file_id` does not exist or belongs to another program; `errors[].code` is `reference_not_found`, with the path in `parameters`), `related_object_not_ready` (an entity is not eligible for its relationship type (`entity_role_missing`), with the entity's path in `parameters`; update the entity, then retry the request unchanged), `related_object_incompatible` (the account holders mix consumer and commercial entities (`account_holder_types_mismatched`), or an account holder is a lead or partner entity, or a `documents[].file_id` references a file whose type is not a compliance document type (`reference_type_mismatched`)), `lead_control_restricted` (your program is not enabled for User Accounts v2; `errors[].code` is `feature_not_enabled`), `idempotency_request_mismatched` (this `Idempotency-Key` was used with a different request body).
- `429`: Rate limit exceeded.
- `500`: Internal server error. Retry with the same `Idempotency-Key`.
- `503`: The service or endpoint is temporarily unavailable. Retry after a delay.
- `504`: An upstream system did not respond in time. Retry with backoff, and with the same `Idempotency-Key` on a `POST` or `PATCH`.

## Changes

- **2026-11-03** `2c659854496e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lead/apis/lead-bank/changes/v2/user_accounts/post.md)

---

[API](https://skmtc.dev/lead/apis/lead-bank.md) - [All operations](https://skmtc.dev/lead/apis/lead-bank/llms.txt) - [OpenAPI document](https://skmtc.dev/lead/apis/lead-bank/revisions/2c659854496e?raw)