> ## 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.

# Account Numbers: Routable addresses for your customers

> What an account number is, which balance it can point at, who holds it, and what you can do with the Account Numbers API.

An account number is a routable payment address. It has a routing number and an account number. Counterparties use them to send you money over ACH, wires, and instant payments. You name the account number by ID when you send money out. You create account numbers for your customers and for your own program accounts. You manage their status and payment controls with the Account Numbers API.

An account number doesn't hold money. It references a balance, and every payment on the account number posts to that balance. You name the balance when you create the account number, and the account number returns it as `balance`. The balance is either a core balance on one of your program's direct core accounts, or a user deposit balance beneath one of your customers' user accounts.

An account number also records who it belongs to. Every account number names an `entity_id`, and that entity is bound at creation.

## Which balance an account number can point at

The table lists each kind of balance and whether an account number can point at it.

| Balance | Allowed | Why |
| - | - | - |
| A core balance on a `direct` core account that Lead has enabled for account number creation | Yes | Your operating, settlement, and similar accounts. Lead sets the permission at onboarding. |
| A user deposit balance | Yes | A customer's deposit balance. Payments on the account number settle to the FBO core balance behind it. |
| A core balance on an `attributed` core account | No | Customer money on an FBO is addressed through the user deposit balances beneath it, not the FBO itself. |
| A core balance on a `shadow` core account | No | Shadow accounts mirror a primary account and don't take payments. |
| A user credit balance | No | Credit balances don't take payments directly. |
| Any balance held by Lead | No | Lead creates the account numbers on balances it holds. You can read them with `GET`. |

## Who holds an account number

Every account number belongs to one entity, and that entity must already exist. Lead checks that it's eligible for one of three roles, `account_holder`, `minor_account_holder`, or `authorized_user`. The entity also needs to already be an account holder or an allowed actor on the account behind the balance. Eligibility comes from the entity's own data, and `minor_account_holder` only applies on programs Lead has approved for minor account holders. See [Entity Eligibility](https://docs.lead.bank/v2/products/entity/eligibility.md).

The role you pick also sets the account number's default payment controls. An `account_holder` starts out accepting everything. A `minor_account_holder` or `authorized_user` starts with the restricted outgoing set described on [Payment controls](https://docs.lead.bank/v2/products/account-number/controls.md). An entity of type `lead` can't hold an account number you create.

There is no unassigned state and no assignment step. If an account number was created for the wrong entity, cancel it and create a new one.

## How account numbers relate to the rest of the model

An account number connects to these objects:

* **Core balance.** An account number on a direct core account makes that balance routable. Read the balance with the [Core Balances API](https://docs.lead.bank/products/core-balance/overview.md).
* **User deposit balance.** An account number on a user deposit balance is how a customer receives and sends money. Lead settles each payment to the core balance behind the user deposit balance.
* **Entity.** The `entity_id` on the account number is the customer or company the account number belongs to. See [Entity](https://docs.lead.bank/v2/products/entity/overview.md).
* **Payments.** ACH, wires, instant payments, and internal transfers reference an account number by `account_number_id`. Lead resolves the balance behind it, and each payment object returns the core balance it posted to as `core_balance_id`.
* **Originators.** An account number that sends ACH under a specific originator sets `ach_controls.originator_id`. The originator's `core_balance_id` must match the account number's balance. See [Originators](https://docs.lead.bank/v2/products/originators/overview.md).

## What you can do

You can use these endpoints:

* `POST /v2/account_numbers`: Create an account number on a balance for an entity. Lead generates the number.
* `POST /v2/account_numbers/register`: Register a number you generated, on a balance for an entity.
* `GET /v2/account_numbers/{account_number_id}`: Retrieve an account number.
* `GET /v2/account_numbers`: List account numbers filtered by `balance_id`, `entity_id`, or `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`.
* `POST /v2/account_numbers/{account_number_id}/cancel`: Permanently cancel an account number.

`POST /v2/account_numbers` and `POST /v2/account_numbers/register` require an `Idempotency-Key` header. The activate, deactivate, and cancel endpoints take no request body but require an `Idempotency-Key`. Calling one of them on an account number already in the target status returns the current object. See [Idempotency](https://docs.lead.bank/api-reference/using-the-api/idempotency-v2.md).

### Authentication

The endpoints use these scopes:

* **`account_number/read_write`** for create, register, update, and status changes. Also grants read access.
* **`account_number/read`** for the GET endpoints only.

## What you can't do

These actions aren't available:

* **Create an account number without a balance and an entity.** Both are required on every create and register request.
* **Create an account number on an FBO, a shadow account, a credit balance, or a balance Lead holds.** The request returns `422`.
* **Reassign an account number to another entity.** There is no assign endpoint. Cancel it and create a new one.
* **Reactivate a canceled account number.** The request returns an error. See [Account Number Statuses](https://docs.lead.bank/v2/products/account-number/statuses.md).
* **Originate payments from an account number Lead holds.** They appear on `GET`, and every rail returns an error when you name one as the sender.
* **Remove an entity from its account while it holds an account number that is `active` or `inactive`.** Cancel the account number first.
* **Reference an `account_id`.** It isn't accepted on requests, returned on responses, or available as a filter.

## In this section

These are the pages in this section:

* [The Account Number Object](https://docs.lead.bank/v2/products/account-number/account-number-object.md)
* [Account Number Statuses](https://docs.lead.bank/v2/products/account-number/statuses.md)
* [Managing account numbers](https://docs.lead.bank/v2/products/account-number/managing.md)
* [Payment controls](https://docs.lead.bank/v2/products/account-number/controls.md)