> ## 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. # Create a User Account > Create a User Account. ## OpenAPI ````yaml POST /v2/user_accounts openapi: 3.0.1 info: title: Lead Bank description: Lead Bank's APIs version: v1.0 servers: - url: https://api.sandbox.lead.bank - url: https://api.lead.bank security: - bearerAuth: [] tags: - name: ACH - name: Account Number - name: OAuth - name: Events - name: Instant Payments - name: Lending - name: Simulation - name: Internal Transfer - name: Disbursement - name: Entity - name: Wire - name: Originator - name: Funding - name: Receivable Sale - name: Balances - name: Compliance - name: Application - name: User Account - name: Blockchain Payment - name: Core Account - name: Core Balance - name: Core Transaction - name: Event Subscription - name: Receivable - name: User Credit Transaction - name: Files paths: /v2/user_accounts: post: tags: - User Account summary: Create a user account description: Create a User Account. operationId: create-a-user-account-v2 parameters: - name: Idempotency-Key in: header description: >- A unique key for this request, up to 255 characters. Retrying with the same key and body returns the original response without creating a second user account. See [Idempotency](https://docs.lead.bank/api-reference/using-the-api/idempotency-v2). required: true schema: type: string maxLength: 255 example: 3f1c9a52-7d4e-4b8a-9c21-6e0f5d2a8b14 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserAccountRequestV2' examples: consumer_deposit: summary: Consumer deposit user account value: requested_features: - deposit product_config_id: product_config_xyz123 entities: account_holders: - entity_consumer_123 product_name: Everyday Checking metadata: {} documents: [] commercial_credit: summary: Commercial credit user account value: application_id: application_xyz123 requested_features: - credit_with_underwriting product_config_id: product_config_xyz123 balance_sheet_model: held_for_investment entities: account_holders: - entity_biz_456 authorized_signers: - entity_signer_789 product_name: Business Credit Line details: underwriting: is_secured: false is_mla: false underwriting_grade: A currency_code: USD available_credit: 5000000 limit: 5000000 max_limit: 10000000 metadata: external_id: BIZ-2024-001 documents: - file_id: file_7RwQ2mK9pL4xT1vN8jS5 timestamp: '2025-11-15T09:00:00Z' responses: '200': description: User account created successfully. content: application/json: schema: $ref: '#/components/schemas/UserAccountV2' '400': description: >- The request could not be parsed (`request_malformed`), or the `Idempotency-Key` header is missing (`idempotency_key_missing`). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: idempotency_key_missing message: >- This endpoint requires an Idempotency-Key header. Add one and resend the request. '403': description: >- `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_allowed` (the request came from an IP address that is not on your program's allowlist). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: token_invalid message: The bearer token is missing, expired, malformed, or invalid. '409': description: >- A concurrent request with the same `Idempotency-Key` is still in flight. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: idempotency_key_in_use message: >- A concurrent request using this Idempotency-Key is still in flight. '413': description: >- 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`). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: content_too_large message: >- The request is over a size limit for this endpoint. Make it smaller and resend it. errors: - code: body_too_large message: metadata is over this endpoint's size limit. parameters: - metadata '422': description: >- 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_conflict` (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_inconsistent` (this `Idempotency-Key` was used with a different request body). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: parameters_invalid message: One or more parameters are invalid. errors: - code: dependent_parameter_required message: >- balance_sheet_model is required when requested_features includes a credit feature. parameters: - balance_sheet_model - code: parameter_bound_exceeded message: >- details.underwriting.limit (10000000) cannot exceed details.underwriting.max_limit (5000000). parameters: - details.underwriting.limit '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limit_exceeded message: >- You have exceeded the rate limit for this endpoint. Retry with backoff. '500': description: Internal server error. Retry with the same `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_server_error message: >- Something went wrong on our end. Contact Lead with the Request-Id if this persists. '503': description: >- The service or endpoint is temporarily unavailable. Retry after a delay. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: service_unavailable message: >- The service is temporarily unavailable. Retry after the indicated delay. '504': description: >- An upstream system did not respond in time. Retry with backoff, and with the same `Idempotency-Key` on a `POST` or `PATCH`. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: gateway_timeout message: An upstream system timed out. Retry with backoff. components: schemas: CreateUserAccountRequestV2: type: object description: Request body for creating a new user account properties: application_id: $ref: '#/components/schemas/ApplicationID' requested_features: type: array description: >- 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). items: $ref: '#/components/schemas/UserAccountFeatureV2' entities: $ref: '#/components/schemas/CreateUserAccountEntitiesV2' product_name: type: string description: Partner's name for their product balance_sheet_model: type: string allOf: - $ref: '#/components/schemas/UserAccountBalanceSheetModelV2' nullable: true description: >- How Lead carries the user account's credit on its balance sheet. Required whenever `requested_features` includes a credit feature. Cannot be changed once set. Learn more about balance sheet model [here](/v2/products/user-accounts/user-account-object#balance-sheet-model). product_config_id: type: string pattern: ^product_config_\w+$ description: >- Identifies the product configuration set up for your program. Provided to you by your Lead Technical Account Manager. Cannot be changed once set. example: product_config_xyz123 details: type: object description: Additional details for the user account properties: underwriting: $ref: '#/components/schemas/CreateUserAccountUnderwritingV2' adverse_action_notice: $ref: '#/components/schemas/AdverseActionNotice' metadata: $ref: '#/components/schemas/Metadata' documents: type: array description: >- Compliance documents linked to the user account. Each entry references a file uploaded with the Files API. Send `[]` when there are none to link yet. items: $ref: '#/components/schemas/FileDocument' required: - requested_features - product_config_id - product_name - entities - documents UserAccountV2: type: object description: A user account object readOnly: true required: - id - status - status_reason - features - product_name - entities - details - documents - metadata - created_at - updated_at properties: id: $ref: '#/components/schemas/UserAccountID' status: $ref: '#/components/schemas/UserAccountStatusV2' status_reason: $ref: '#/components/schemas/UserAccountStatusReasonV2' application_id: $ref: '#/components/schemas/ApplicationID' features: type: array description: Features granted to the user account. items: $ref: '#/components/schemas/UserAccountFeatureV2' entities: $ref: '#/components/schemas/UserAccountEntitiesV2' details: $ref: '#/components/schemas/UserAccountDetailsV2' product_name: type: string description: Partner's name for their product documents: type: array description: >- Compliance documents linked to the user account. Each entry references a file uploaded with the Files API. items: $ref: '#/components/schemas/FileDocument' legacy_documents: type: array readOnly: true description: >- Document entries created on v0 User Accounts, returned exactly as sent. Read only: ignored if included on a POST or PATCH. items: $ref: '#/components/schemas/LegacyUserAccountDocumentV2' client_account_id: type: string description: >- 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`. readOnly: true balance_sheet_model: type: string allOf: - $ref: '#/components/schemas/UserAccountBalanceSheetModelV2' nullable: true description: How Lead carries the user account's credit on its balance sheet. product_config_id: type: string pattern: ^product_config_\w+$ nullable: true description: >- The id of the product configuration the user account was created under. `null` only on user accounts created before product config ids existed. example: product_config_xyz123 metadata: $ref: '#/components/schemas/Metadata' created_at: type: string format: date-time description: Creation timestamp readOnly: true updated_at: type: string format: date-time description: Last update timestamp readOnly: true closed_at: type: string format: date-time description: >- Timestamp when the user account was closed. Updated by /close endpoint. readOnly: true nullable: true Error: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- A human-readable description of the error family. Identical for every occurrence of a given `code`; carries no request-specific detail. example: One or more parameters are invalid. errors: type: array description: >- Zero or more specific errors within this family. Always present for validation errors, one entry per failing field. items: $ref: '#/components/schemas/ErrorItem' ApplicationID: type: string description: Unique identifier for the application. Prefixed with `application_`. example: application_xyz123 pattern: ^application_\w+$ UserAccountFeatureV2: type: string description: A feature of the user account enum: - deposit - credit_with_underwriting - credit_without_underwriting CreateUserAccountEntitiesV2: type: object description: > 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. properties: account_holders: type: array description: Account holders (min 1, max 20) items: $ref: '#/components/schemas/EntityID' minItems: 1 maxItems: 20 authorized_signers: type: array description: >- Authorized signers on the user account (required with min 1 if business/sole_prop account holders) items: $ref: '#/components/schemas/EntityID' maxItems: 20 authorized_users: type: array description: Authorized users on the user account items: $ref: '#/components/schemas/EntityID' maxItems: 20 required: - account_holders UserAccountBalanceSheetModelV2: type: string description: How Lead carries the user account's credit on its balance sheet. enum: - held_for_investment - held_for_sale CreateUserAccountUnderwritingV2: type: object description: >- Underwriting details for creating a user account. All fields are required except `scra` and `report`. required: - is_secured - is_mla - underwriting_grade - currency_code - available_credit - limit - max_limit properties: is_secured: type: boolean description: Indicates if this is a secured credit/deposit product is_mla: type: boolean description: >- Indicates if this user account is considered a Military Lending Act account underwriting_grade: type: string description: Grade given to the customer based on underwriting currency_code: type: string description: The currency for the user account (3-letter ISO code) example: USD available_credit: type: integer description: Available credit for the customer to draw (in minor units) limit: type: integer description: Current credit limit (in minor units) max_limit: type: integer description: Maximum credit limit approved in underwriting (in minor units) scra: $ref: '#/components/schemas/Scra' report: $ref: '#/components/schemas/CreditReport' AdverseActionNotice: type: object description: Adverse action notice information properties: delivered_at: type: string format: date-time description: >- ISO 8601 timestamp when the adverse action notice was sent to the applicant. reason: type: string description: The reason stated in the adverse action notice. delivery_method: type: string description: >- How the notice was delivered to the applicant. Possible values: `email`, `text`, `other`. enum: - email - text - other required: - delivered_at - reason - delivery_method Metadata: type: object additionalProperties: type: string description: >- A set of key-value pairs that can be used to store additional information related to this object. FileDocument: type: object description: >- A document entry in a v2 Application or User Account `documents` array: a reference to an uploaded file plus the moment the end user saw or agreed to it. The file's `type` is not repeated here; retrieve it via `GET /v2/files/{id}`. Entity document entries have their own shape and are specified with the v2 Entity operations. required: - file_id - timestamp properties: file_id: $ref: '#/components/schemas/FileID' timestamp: type: string format: date-time description: |- 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. example: '2026-09-14T14:20:11Z' version: type: string description: >- 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). example: v2 UserAccountID: type: string description: The ID of the User Account object. example: user_account_xyz123 pattern: ^user_account_\w+$ UserAccountStatusV2: type: string description: Current state of the user account enum: - active - inactive - closed UserAccountStatusReasonV2: type: string description: Machine-readable reason for the current status enum: - client_closed - entity_closed - frozen - dormant - active - paid_off - charged_off - canceled - other UserAccountEntitiesV2: type: object readOnly: true description: Entity relationships associated with the user account (response only) properties: account_holder_type: type: string description: Derived from the type of the entity referenced in account_holders enum: - consumer - commercial UserAccountDetailsV2: type: object description: Core details of the user account readOnly: true properties: underwriting: $ref: '#/components/schemas/UserAccountUnderwritingV2' adverse_action_notice: $ref: '#/components/schemas/AdverseActionNotice' LegacyUserAccountDocumentV2: type: object description: >- A document entry sent through the v0 Accounts API, returned exactly as sent. Read only. properties: document_id: type: string description: >- The SFTP filename sent on v0 as the document reference. Lead did not check that the file arrived. example: loan_agreement_01_2026.pdf type: $ref: '#/components/schemas/ComplianceDocumentType' displayed_at: type: string format: date-time description: >- When the document was shown to the account holder, as sent on v0. Present on disclosure documents. consented_at: type: string format: date-time description: >- When the account holder consented to the document, as sent on v0. Present on consent documents. version: type: string description: The version label sent on v0. example: v1 ErrorCode: type: string description: >- A snake_case code identifying the error family — the stable, machine-readable value partners branch on, together with the HTTP status. example: parameters_invalid enum: - request_malformed - content_too_large - idempotency_key_missing - authentication_missing - token_invalid - source_ip_not_allowed - url_invalid - object_not_found - method_not_allowed - idempotency_key_in_use - idempotency_request_inconsistent - rate_limit_exceeded - internal_server_error - service_unavailable - endpoint_disabled - gateway_timeout - unclassified - parameters_invalid - related_object_invalid - related_object_not_ready - related_object_conflict - limit_exceeded - client_control_restricted - lead_control_restricted - object_state_conflict - object_modified_concurrently - operation_invalid ErrorItem: type: object required: - code - message properties: code: type: string description: A snake_case code naming the specific error or sub-category. example: required message: type: string description: >- A human-readable description of this specific error, with interpolated values where relevant. example: account_number_id is required. parameters: type: array description: >- The request fields this error implicates, in dot notation for nested fields. Present for validation errors. items: type: string example: - account_number_id EntityID: type: string description: The ID of your entity. example: entity_xyz123 pattern: ^entity_[^\s]{1,33}$ Scra: type: object description: SCRA (Servicemembers Civil Relief Act) details properties: start_date: type: string format: date description: Start date for SCRA protections end_date: type: string format: date description: End date for SCRA protections required: - start_date CreditReport: type: object description: > 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. required: - pulled_at - source properties: score: type: integer description: >- Credit score returned by the bureau. Supported range is 300-850. Mutually exclusive with `non_score_value`. minimum: 300 maximum: 850 non_score_value: type: string description: >- Indicates the state of a credit file when a numeric score is not available. Mutually exclusive with `score`. enum: - unestablished - frozen pulled_at: type: string format: date-time description: ISO 8601 timestamp when the credit report was pulled. source: type: string description: >- Credit bureau that issued the report. Possible values: `equifax`, `experian`, `transunion`. enum: - equifax - transunion - experian FileID: type: string description: Lead-issued identifier of the file, from `POST /v2/files`. example: file_7RwQ2mK9pL4xT1vN8jS5 pattern: ^file_\w+$ UserAccountUnderwritingV2: type: object description: Underwriting details for the user account properties: is_secured: type: boolean description: Indicates if this is a secured credit/deposit product is_mla: type: boolean description: >- Indicates if this user account is considered a Military Lending Act account underwriting_grade: type: string description: Grade given to the customer based on underwriting currency_code: type: string description: The currency for the user account (3-letter ISO code) example: USD available_credit: type: integer description: Available credit for the customer to draw (in minor units) limit: type: integer description: Current credit limit (in minor units) max_limit: type: integer description: Maximum credit limit approved in underwriting (in minor units) scra: $ref: '#/components/schemas/Scra' report: $ref: '#/components/schemas/CreditReport' ComplianceDocumentType: type: string description: Type of document associated with an application enum: - 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 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.