POST /v2/account_numbers, update its controls and metadata with PATCH /v2/account_numbers/{account_number_id}, and read it with GET /v2/account_numbers/{account_number_id}. Create and register require an Idempotency-Key header. See Idempotency.
This example is the account number on Acme’s operating account, held by Acme’s own entity. It sends ACH under Acme’s main originator, so ach_controls.originator_id is set. Acme has locked it down. Incoming ACH debits come only from its two payroll tax processors. Outgoing ACH and wires go only to a short list of vendor accounts. International wires are off, and internal transfers run only against Acme’s settlement account. Incoming instant payments are open.
ach_controls.originator_id. It’s set only when the balance is a core balance, because an originator settles to a core balance and the two must match. On a user deposit balance it’s always null. Entries go out under the originator Lead configured for your program at onboarding.
Fields
The table lists each field on the object.The balance block
The table lists the fields in the balance block.
The balance is set on create and can’t be changed. For
core_balance, the balance must sit on a direct core account that Lead has enabled for account number creation. For user_deposit_balance, payments on the account number settle to the FBO core balance the user deposit balance sits on.
This example is an account number for one of Acme’s customers, on that customer’s user deposit balance. Acme kept every control at its default, so the account number accepts and sends on every rail.
"originator_id": null[a],
"incoming": {
"accept_credit": true,
"accept_debit": true,
"counterparty_filter": "accept_all",
"counterparty_company_ids_allowlist": []
},
"outgoing": {
"counterparty_filter": "accept_all",
"counterparty_account_numbers_allowlist": []
}
},
"wire_controls": {
"incoming": {
"counterparty_filter": "accept_all",
"counterparty_account_numbers_allowlist": []
},
"outgoing": {
"counterparty_filter": "accept_all",
"counterparty_account_numbers_allowlist": []
},
"outgoing_international": {
"counterparty_filter": "accept_all",
"counterparty_international_account_numbers_allowlist": []
}
},
"internal_transfer_controls": {
"incoming": {
"counterparty_filter": "accept_all",
"counterparty_account_number_ids_allowlist": []
},
"outgoing": {
"counterparty_filter": "accept_all",
"counterparty_account_number_ids_allowlist": []
}
},
"instant_payment_controls": {
"incoming": {
"counterparty_filter": "accept_all",
"counterparty_account_numbers_allowlist": []
},
"outgoing": {
"counterparty_filter": "accept_all",
"counterparty_account_numbers_allowlist": []
}
},
"metadata": {},
"created_at": "2026-10-08T11:40:27Z",
"updated_at": "2026-10-08T11:40:27Z"
}
Payment controls
Each rail has a controls block that you set on create and change withPATCH. The fields, the counterparty_filter values (accept_all, allowlist_only, reject_all), the allowlist fields, and the default behavior are documented on Payment controls.
ach_controls.originator_id names the originator this account number sends ACH under. The originator’s core_balance_id must match the account number’s balance. A mismatch returns 422. See The Originator Object.
Creating an account number
POST /v2/account_numbers and POST /v2/account_numbers/register take the same body, except that register also requires account_number.
Lead checks the following before it creates the account number. Each failure returns 422.
Listing account numbers
GET /v2/account_numbers returns a list (objects, has_more). Filter by any of:
Account numbers on balances Lead holds are included in list results.
Coming from v1
A v2 account number replaces the v1 account number. Account numbers created on/v1/account_number are readable on /v2/account_numbers with balance populated.