---
title: "Create a Funding"
method: POST
path: "/v2/fundings"
tags: ["Funding"]
---

# Create a Funding

`POST /v2/fundings`

## Request

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

Create a Funding to disburse principal from a User Credit Balance to an Account Number. The response returns the Funding with `status: processing`. See [Funding Object](/v2/products/fundings/funding-object) for the checks Lead runs on create.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `user_credit_balance_id` string, required: ID of the User Credit Balance this funding draws against. The balance must be `active`; if it has an `expected_maturity_date`, that date must not be in the past.
  - `account_number_id` string, required: The ID of the Lead Bank Account Number object.
  - `currency_code` 'USD', required: A three-letter currency code as defined in ISO 4217.
  - `amount` integer, required: The total principal to disburse, in minor units. Must be greater than zero. For a `non_revolving` balance, the sum of this amount and all prior `processing` or `posted` fundings on the balance must not exceed its `max_funding_amount`.
  - `metadata` object: Additional metadata associated with the funding.

## Response `200`

The Funding object was accepted for processing.

- FundingV2
  - `id` string, required: Unique ID of the Funding object.
  - `user_credit_balance_id` string, required: ID of the User Credit Balance this funding draws against.
  - `account_number_id` string, required: The ID of the Lead Bank Account Number object.
  - `currency_code` 'USD', required: A three-letter currency code as defined in ISO 4217.
  - `amount` integer, required: The total principal disbursed, in minor units.
  - `metadata` object: Additional metadata associated with the funding.
  - `core_transaction_id` string, nullable, required: ID of the Core Transaction that credited the destination balance. `null` until the funding is `posted`.
  - `status` 'processing' | 'posted' | 'rejected', required: The current status of the Funding object.
  - `rejection` FundingRejection, required: Object containing information relevant for cases where the Funding object is in a rejected status. When the object is not in a rejected status, fields will still be present with empty strings.
    - `reason` 'internal_error': The rejection code that indicates the type of rejection. Note that Lead may introduce additional enums in the future; partner integrations should be ready to handle them as non-breaking changes.
    - `details` string: Additional info about the rejection. Reserved for future use.
  - `created_at` string, date-time, required: The ISO-8601 timestamp at which the Funding object was created.
  - `updated_at` string, date-time, required: The ISO-8601 timestamp at which the Funding object was last updated.

## Other responses

- `400`: The request could not be parsed (`request_malformed`), or the `Idempotency-Key` header is missing (`idempotency_key_missing`).
- `403`: Rejected before the request reached the Funding 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).
- `404`: The referenced User Credit Balance or Account Number does not exist or is not visible to this program. Whether body references surface as `404 object_not_found` or `422 related_object_invalid` is under review; integrate against both.
- `409`: A concurrent request with the same `Idempotency-Key` is still in flight.
- `422`: The request was parsed but cannot be processed. `code` is one of: `parameters_invalid` (a field is missing, malformed, or out of range; all failures returned at once), `related_object_invalid` (a referenced balance or account number does not exist or cannot be used), `related_object_not_ready` (the balance or account number is not `active`), `related_object_incompatible` (`currency_code` does not match the balance), `limit_exceeded` (the funding would exceed the balance's `max_funding_amount`), `operation_invalid` (the balance's `expected_maturity_date` has passed), `lead_control_restricted` (the destination is not permitted to receive fundings, or the program has no funding destination configured), `idempotency_request_mismatched` (this `Idempotency-Key` was used with a different request body).
- `429`: Rate limit exceeded.
- `500`: Internal server error.
- `503`: The endpoint is temporarily disabled. Retry after the interval given in the `Retry-After` header.
- `504`: An upstream system did not respond in time. Nothing was persisted; retry with backoff.

## Changes

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

[Operation history](https://skmtc.dev/lead/apis/lead-bank/changes/v2/fundings/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)