Managing account numbers

Use these endpoints to create account numbers, update them, and change their status:

Endpoint	Description
`POST /v2/account_numbers`	Create an account number on a balance for an entity. Lead generates the number. Requires `balance` and `entity_id`, and an `Idempotency-Key` header.
`POST /v2/account_numbers/register`	Register a number you generated. Same body as create, plus `account_number`. Requires an `Idempotency-Key` header.
`GET /v2/account_numbers`	List account numbers filtered by `balance_id`, `entity_id`, or `account_number`.
`GET /v2/account_numbers/{account_number_id}`	Retrieve an account number.
`PATCH /v2/account_numbers/{account_number_id}`	Update payment controls or metadata.
`POST /v2/account_numbers/{account_number_id}/activate`	Return an `inactive` account number to `active`.
`POST /v2/account_numbers/{account_number_id}/deactivate`	Move an `active` account number to `inactive`. It can no longer send or receive.
`POST /v2/account_numbers/{account_number_id}/cancel`	Permanently cancel an account number. You can’t undo this, and the number isn’t reused.

The activate, deactivate, and cancel endpoints take no request body but require an Idempotency-Key. Calling one on an account number already in the target status returns the current object. See Idempotency. The entity is bound when the account number is created, and every account number starts active. An account number sends and receives only while it is active. See Account Number Statuses for the full lifecycle. See Payment controls for the per-rail settings you can manage with the update endpoint.

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

​Related

Related