> ## 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. `user_account_id` comes from the URL path, not the request body. New User Credit Balances have `status: active`. ## OpenAPI ````yaml POST /v2/user_accounts/{user_account_id}/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_accounts/{user_account_id}/user_credit_balances: post: tags: - User Credit Balance summary: Create a Credit Balance description: >- Create a User Credit Balance under an existing User Account. `user_account_id` comes from the URL path, not the request body. New User Credit Balances have `status: active`. operationId: create-a-user-credit-balance parameters: - name: user_account_id in: path required: true description: The parent User Account's ID schema: type: string pattern: ^user_account_\w+$ - name: Idempotency-Key in: header description: Idempotency key required: true schema: type: string maxLength: 255 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' '400': description: The request could not be parsed, or a required header is missing. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: request_malformed message: The request is invalid and cannot be parsed by the server. errors: - code: payload_invalid message: The request body is not valid JSON. '403': description: >- Rejected before the request reached the User Credit Balance API. `code` is one of: `authentication_missing` (the request has no credentials), `token_invalid` (the bearer token is expired, invalid, or does not grant the required scope), `source_ip_not_permitted` (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: 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 '404': description: The parent User Account ID passed in is not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: object_not_found message: >- No object exists at the requested ID, or it is not visible to this caller. '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. '422': description: Your request parameters did not validate. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: parameters_invalid message: One or more parameters are invalid. errors: - code: required message: name is required. parameters: - name '429': description: You've reached the rate limit for this call. 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. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_server_error message: >- An unexpected error occurred. Contact support with the Request-Id header value. '503': description: >- The endpoint is temporarily disabled. Retry after the interval given in the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: endpoint_disabled message: >- This endpoint is temporarily disabled. Retry after the interval given in the Retry-After header. '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: CreateUserCreditBalanceRequest: type: object description: Request body for creating a new User Credit Balance. additionalProperties: false required: - name - currency_code - interest - autopay_method - details properties: name: type: string minLength: 1 maxLength: 64 pattern: \S currency_code: $ref: '#/components/schemas/CurrencyCode' interest: type: object additionalProperties: false required: - rate - effective_rate - effective_apr properties: rate: type: string effective_rate: type: string effective_apr: type: string autopay_method: type: string enum: - ach - debit_card - wire - virtual_wallet - credit_card - none details: oneOf: - $ref: '#/components/schemas/CreateUserCreditBalanceRevolvingDetail' - $ref: '#/components/schemas/CreateUserCreditBalanceNonRevolvingDetail' discriminator: propertyName: structure mapping: revolving: '#/components/schemas/CreateUserCreditBalanceRevolvingDetail' non_revolving: '#/components/schemas/CreateUserCreditBalanceNonRevolvingDetail' metadata: $ref: '#/components/schemas/Metadata' UserCreditBalance: type: object description: A user credit balance — a virtual end-customer credit position. properties: id: type: string pattern: ^user_credit_balance_\w+$ user_account_id: type: string 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 - client_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: type: object properties: accrued: type: integer description: Total fees accrued to date, minor units. rewards: type: object properties: amount: type: integer unit: type: string enum: - USD - points dispute: type: object properties: amount: type: integer amount_breakdown: $ref: '#/components/schemas/UserCreditBalanceAmountBreakdown' charge_off: type: object properties: amount: type: integer amount_breakdown: $ref: '#/components/schemas/UserCreditBalanceAmountBreakdown' past_due: type: object properties: amount: type: integer past_due_days: type: integer amount_breakdown: $ref: '#/components/schemas/UserCreditBalanceAmountBreakdown' interest: type: object properties: rate: type: string description: Contractual annual interest rate, decimal(M,6). effective_rate: type: string description: True annualized accrual rate, decimal(M,6). effective_apr: type: string description: APR as disclosed to borrower, decimal(M,3). autopay_method: type: string enum: - ach - debit_card - wire - virtual_wallet - credit_card - none details: type: object properties: structure: type: string enum: - revolving - non_revolving expected_maturity_date: type: string format: date repayment_details: 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. max_funding_amount: type: integer description: Minor units. term: type: object properties: length: type: integer unit: type: string enum: - days - weeks - months - years expected_finance_charge_amount: type: integer description: Minor units. metadata: $ref: '#/components/schemas/Metadata' created_at: type: string format: date-time updated_at: type: string format: date-time closed_at: type: string format: date-time 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' CurrencyCode: description: A three-letter currency code as defined in ISO 4217. type: string example: USD enum: - USD CreateUserCreditBalanceRevolvingDetail: type: object additionalProperties: false required: - structure properties: structure: type: string enum: - revolving repayment_details: $ref: >- #/components/schemas/CreateUserCreditBalanceRepaymentDetailsRevolving CreateUserCreditBalanceNonRevolvingDetail: type: object additionalProperties: false required: - structure - expected_maturity_date - repayment_details - max_funding_amount - term - expected_finance_charge_amount properties: structure: type: string enum: - non_revolving expected_maturity_date: type: string format: date repayment_details: $ref: >- #/components/schemas/CreateUserCreditBalanceRepaymentDetailsNonRevolving max_funding_amount: type: integer description: Minor units. minimum: 0 exclusiveMinimum: true term: type: object additionalProperties: false 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. 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. UserCreditBalancePaymentFrequency: type: string enum: - business_daily - weekly - biweekly - semi_monthly - monthly - quarterly - semi_annually - annually - fixed_interval - maturity - variable 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 CreateUserCreditBalanceRepaymentDetailsRevolving: allOf: - type: object additionalProperties: false required: - expected_payment_frequency properties: expected_payment_frequency: $ref: '#/components/schemas/UserCreditBalancePaymentFrequency' expected_payment_frequency_interval_days: type: integer minimum: 1 maximum: 730 - $ref: '#/components/schemas/CreateUserCreditBalanceIntervalDaysRule' CreateUserCreditBalanceRepaymentDetailsNonRevolving: allOf: - type: object additionalProperties: false 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 - $ref: '#/components/schemas/CreateUserCreditBalanceIntervalDaysRule' CreateUserCreditBalanceIntervalDaysRule: description: >- Structure-independent conditional: expected_payment_frequency_interval_days is required when expected_payment_frequency is fixed_interval, and must not be present otherwise. Combined via allOf with the base repayment_details object on create only — on PATCH this depends on the stored value too, so it stays a Go-side check. oneOf: - properties: expected_payment_frequency: enum: - fixed_interval required: - expected_payment_frequency_interval_days - properties: expected_payment_frequency: not: enum: - fixed_interval not: required: - expected_payment_frequency_interval_days securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.