> ## 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 Credit Balance

> Create a User Credit Balance under an existing User Account. Send the parent User Account's ID as `user_account_id` in the request body. New User Credit Balances have `status: active`.

> [!NOTE]
>
> See [Errors](https://docs.lead.bank/api-reference/using-the-api/errors-v2.md) for the common errors every v2 endpoint can return.


## OpenAPI

````yaml https://docs.lead.bank/openapi.json POST /v2/user_credit_balances
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_credit_balances:
    post:
      tags:
        - User Credit Balance
      summary: Create a Credit Balance
      description: >-
        Create a User Credit Balance under an existing User Account. Send the
        parent User Account's ID as `user_account_id` in the request body. New
        User Credit Balances have `status: active`.
      operationId: create-a-user-credit-balance-v2
      parameters:
        - name: Idempotency-Key
          in: header
          description: Idempotency key
          required: true
          schema:
            type: string
            maxLength: 255
            minLength: 5
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserCreditBalanceRequest'
      responses:
        '200':
          description: Credit Balance created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCreditBalance'
        4XX:
          $ref: '#/components/responses/ErrorDefault'
        5XX:
          $ref: '#/components/responses/ErrorServer'
components:
  schemas:
    CreateUserCreditBalanceRequest:
      type: object
      description: Request body for creating a new User Credit Balance.
      required:
        - user_account_id
        - name
        - currency_code
        - autopay_method
        - terms
      properties:
        user_account_id:
          $ref: '#/components/schemas/UserAccountID'
          description: The ID of the parent User Account.
        name:
          type: string
          minLength: 1
          maxLength: 64
          pattern: \S
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        autopay_method:
          type: string
          enum:
            - ach
            - debit_card
            - wire
            - virtual_wallet
            - credit_card
            - none
        terms:
          $ref: '#/components/schemas/CreateUserCreditBalanceTerms'
        metadata:
          $ref: '#/components/schemas/Metadata'
    UserCreditBalance:
      type: object
      description: A user credit balance — a virtual end-customer credit position.
      required:
        - id
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/UserCreditBalanceID'
        user_account_id:
          $ref: '#/components/schemas/UserAccountID'
          description: The parent User Account's ID.
        name:
          type: string
          description: Human-readable name.
          example: Personal Loan - Jane Smith
        status:
          type: string
          enum:
            - active
            - inactive
            - closed
            - reporting_stopped
        status_reason:
          type: string
          enum:
            - active
            - frozen
            - dormant
            - other
            - entity_closed
            - partner_closed
            - paid_off
            - charged_off
            - canceled
            - receivables_sold_to_partner
            - data_not_available
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        amount:
          type: integer
          description: Signed, minor units.
        amount_in_usd:
          type: integer
          description: Signed, minor units, in USD.
        amount_breakdown:
          $ref: '#/components/schemas/UserCreditBalanceAmountBreakdown'
        fees:
          $ref: '#/components/schemas/UserCreditBalanceFees'
        rewards:
          $ref: '#/components/schemas/UserCreditBalanceRewards'
        dispute:
          $ref: '#/components/schemas/UserCreditBalanceDispute'
        charge_off:
          $ref: '#/components/schemas/UserCreditBalanceChargeOff'
        past_due:
          $ref: '#/components/schemas/UserCreditBalancePastDue'
        autopay_method:
          type: string
          enum:
            - ach
            - debit_card
            - wire
            - virtual_wallet
            - credit_card
            - none
        terms:
          $ref: '#/components/schemas/UserCreditBalanceTerms'
        metadata:
          $ref: '#/components/schemas/Metadata'
        created_at:
          type: string
          format: date-time
        closed_at:
          type: string
          format: date-time
          nullable: true
    UserAccountID:
      type: string
      description: The ID of the User Account object.
      example: user_account_xyz123
      pattern: ^user_account_\w+$
    CurrencyCode:
      description: A three-letter currency code as defined in ISO 4217.
      type: string
      example: USD
      enum:
        - USD
    CreateUserCreditBalanceTerms:
      type: object
      description: >-
        The rates are always required. Which other fields apply depends on
        `structure`. When

        `structure` is `non_revolving`, `expected_maturity_date`, `repayment`,
        `max_funding_amount`,

        `duration`, and `expected_finance_charge_amount` are required. When
        `structure` is

        `revolving`, only `repayment` is allowed, and it's optional.
      required:
        - structure
        - interest_rate
        - effective_interest_rate
        - effective_apr
      properties:
        structure:
          type: string
          enum:
            - revolving
            - non_revolving
        interest_rate:
          $ref: '#/components/schemas/Decimal6'
        effective_interest_rate:
          $ref: '#/components/schemas/Decimal6'
        effective_apr:
          $ref: '#/components/schemas/Decimal6'
        expected_maturity_date:
          type: string
          format: date
        repayment:
          $ref: '#/components/schemas/CreateUserCreditBalanceRepaymentDetails'
        max_funding_amount:
          type: integer
          description: Minor units.
          minimum: 0
          exclusiveMinimum: true
        duration:
          type: object
          required:
            - length
            - unit
          properties:
            length:
              type: integer
              minimum: 0
              exclusiveMinimum: true
            unit:
              type: string
              enum:
                - days
                - weeks
                - months
                - years
        expected_finance_charge_amount:
          type: integer
          description: Minor units.
          minimum: 0
    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.
    UserCreditBalanceID:
      type: string
      description: The ID of the User Credit Balance object.
      pattern: ^user_credit_balance_[0-9A-Za-z]{27}$
      example: user_credit_balance_1HCpXwx2EK9oYluWbacgeCnFcLf
    UserCreditBalanceAmountBreakdown:
      type: object
      properties:
        principal:
          type: integer
          description: Principal portion, minor units.
        interest:
          type: integer
          description: Interest portion, minor units.
        fees:
          type: integer
          description: Fees portion, minor units.
    UserCreditBalanceFees:
      type: object
      properties:
        accrued:
          type: integer
          description: Total fees accrued to date, minor units.
    UserCreditBalanceRewards:
      type: object
      properties:
        amount:
          type: integer
        unit:
          type: string
          enum:
            - USD
            - points
    UserCreditBalanceDispute:
      type: object
      properties:
        amount:
          type: integer
        amount_breakdown:
          $ref: '#/components/schemas/UserCreditBalanceAmountBreakdown'
    UserCreditBalanceChargeOff:
      type: object
      properties:
        amount:
          type: integer
        amount_breakdown:
          $ref: '#/components/schemas/UserCreditBalanceAmountBreakdown'
    UserCreditBalancePastDue:
      type: object
      properties:
        amount:
          type: integer
        days:
          type: integer
        amount_breakdown:
          $ref: '#/components/schemas/UserCreditBalanceAmountBreakdown'
    UserCreditBalanceTerms:
      type: object
      properties:
        structure:
          type: string
          enum:
            - revolving
            - non_revolving
        interest_rate:
          allOf:
            - $ref: '#/components/schemas/Decimal6'
          description: Contractual annual interest rate, decimal(M,6).
        effective_interest_rate:
          allOf:
            - $ref: '#/components/schemas/Decimal6'
          description: True annualized accrual rate, decimal(M,6).
        effective_apr:
          allOf:
            - $ref: '#/components/schemas/Decimal6'
          description: APR as disclosed to borrower, decimal(M,6).
        expected_maturity_date:
          type: string
          format: date
        repayment:
          $ref: '#/components/schemas/UserCreditBalanceRepaymentDetails'
        max_funding_amount:
          type: integer
          description: Minor units.
        duration:
          $ref: '#/components/schemas/UserCreditBalanceTermsDuration'
        expected_finance_charge_amount:
          type: integer
          description: Minor units.
    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'
    Decimal6:
      type: string
      description: Decimal string with exactly 6 digits after the decimal point.
      pattern: ^(0|[1-9]\d*)\.\d{6}$
      example: '5.250000'
    CreateUserCreditBalanceRepaymentDetails:
      type: object
      description: >-
        The expected repayment schedule.
        `expected_payment_frequency_interval_days` is required when

        `expected_payment_frequency` is `fixed_interval`, and must be absent
        otherwise. When

        `terms.structure` is `revolving`, only `expected_payment_frequency` and

        `expected_payment_frequency_interval_days` are allowed.
      required:
        - expected_payment_frequency
      properties:
        expected_payment_frequency:
          $ref: '#/components/schemas/UserCreditBalancePaymentFrequency'
        expected_payment_frequency_interval_days:
          type: integer
          minimum: 1
          maximum: 730
        expected_number_of_payments:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        expected_first_payment_date:
          type: string
          format: date
        expected_first_payment_amount:
          type: integer
          description: Minor units.
          minimum: 0
          exclusiveMinimum: true
        expected_last_payment_date:
          type: string
          format: date
        expected_last_payment_amount:
          type: integer
          description: Minor units.
          minimum: 0
          exclusiveMinimum: true
        expected_payment_amount:
          type: integer
          description: Minor units.
          minimum: 0
          exclusiveMinimum: true
    UserCreditBalanceRepaymentDetails:
      type: object
      properties:
        expected_payment_frequency:
          $ref: '#/components/schemas/UserCreditBalancePaymentFrequency'
        expected_payment_frequency_interval_days:
          type: integer
        expected_number_of_payments:
          type: integer
        expected_first_payment_date:
          type: string
          format: date
        expected_first_payment_amount:
          type: integer
          description: Minor units.
        expected_last_payment_date:
          type: string
          format: date
        expected_last_payment_amount:
          type: integer
          description: Minor units.
        expected_payment_amount:
          type: integer
          description: Minor units.
    UserCreditBalanceTermsDuration:
      type: object
      properties:
        length:
          type: integer
        unit:
          type: string
          enum:
            - days
            - weeks
            - months
            - years
    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
        - headers_invalid
        - unsupported_media_type
        - authentication_missing
        - token_invalid
        - source_ip_not_permitted
        - url_invalid
        - object_not_found
        - method_not_allowed
        - idempotency_key_in_use
        - idempotency_request_mismatched
        - rate_limit_exceeded
        - internal_server_error
        - service_unavailable
        - endpoint_disabled
        - gateway_timeout
        - parameters_invalid
        - related_object_invalid
        - related_object_not_ready
        - related_object_incompatible
        - limit_exceeded
        - partner_control_restricted
        - lead_control_restricted
        - object_state_mismatched
        - 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: schema_violation
        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 that caused this error, as `jq` paths without the
            leading dot. For example, a nested field is `address.city` and an
            array item is `beneficial_owners[1].ownership`. A key with
            characters other than letters, digits, and underscores is
            JSON-quoted, like `metadata["order.id"]`. Headers appear by name,
            like `Idempotency-Key`. Present for validation errors.
          items:
            type: string
          example:
            - account_number_id
    UserCreditBalancePaymentFrequency:
      type: string
      enum:
        - business_daily
        - weekly
        - biweekly
        - semi_monthly
        - monthly
        - quarterly
        - semi_annually
        - annually
        - fixed_interval
        - maturity
        - variable
  responses:
    ErrorDefault:
      description: >-
        Error. The response body is an Error object; `code` identifies the error
        family and `errors` lists field-level detail where applicable. See the
        Errors guide for the full list of codes per status.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: authentication_missing
            message: >-
              The request has no authentication credentials. Send your API token
              in the Authorization header.
            errors:
              - code: authentication_missing
                message: >-
                  The Authorization header is missing. Send your API token as a
                  bearer token.
                parameters:
                  - Authorization
    ErrorServer:
      description: >-
        Server error. The response body is an Error object; `code` identifies
        the error family. See the Errors guide for the full list of codes per
        status.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: internal_server_error
            message: >-
              Internal server error. Retry with exponential backoff. For a POST,
              PATCH or DELETE, reuse the same Idempotency-Key so the request
              isn't processed twice. If it keeps failing, contact Lead with the
              Lead-Request-ID.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````