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

# The Account Number Object

> Field-level reference for the Account Number object, including the balance block, the entity it belongs to, payment controls, list filters, and how it maps from the v1 Account Numbers API.

An account number is a routable payment address that references one balance and belongs to one entity. You create one with `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](https://docs.lead.bank/api-reference/using-the-api/idempotency-v2.md).

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.

```json theme={null}
{
  "id": "account_number_2fTZ4St5HSJnxzv7jdevxQnev3U",
  "account_number": "123412341234",
  "routing_number": "123456789",
  "balance": {
    "type": "core_balance",
    "id": "core_balance_2xYw9Kn3Jp7QuS2lY5mAbC0dE4f"
  },
  "entity_id": "entity_2xYv6Kn3Jp7QuS2lY5mAbC0dE4f",
  "status": "active",
  "ach_controls": {
    "originator_id": "originator_2HpKd8Vb3NkXz6mYrT4wE1aQ7s",
    "incoming": {
      "accept_credit": true,
      "accept_debit": true,
      "counterparty_filter": "allowlist_only",
      "counterparty_company_ids_allowlist": [
        "1234567892",
        "1234567893"
      ]
    },
    "outgoing": {
      "counterparty_filter": "allowlist_only",
      "counterparty_account_numbers_allowlist": [
        {
          "type": "us_domestic",
          "account_number": "9876543210",
          "routing_number": "123456789"
        },
        {
          "type": "us_domestic",
          "account_number": "4455667788",
          "routing_number": "123456789"
        }
      ]
    }
  },
  "wire_controls": {
    "incoming": {
      "counterparty_filter": "accept_all",
      "counterparty_account_numbers_allowlist": []
    },
    "outgoing": {
      "counterparty_filter": "allowlist_only",
      "counterparty_account_numbers_allowlist": [
        {
          "type": "us_domestic",
          "account_number": "9876543210",
          "routing_number": "123456789"
        }
      ]
    },
    "outgoing_international": {
      "counterparty_filter": "reject_all",
      "counterparty_international_account_numbers_allowlist": []
    }
  },
  "internal_transfer_controls": {
    "incoming": {
      "counterparty_filter": "allowlist_only",
      "counterparty_account_number_ids_allowlist": [
        "account_number_3gUA5Tu6ITKoyAw8kefwyRofw4V"
      ]
    },
    "outgoing": {
      "counterparty_filter": "allowlist_only",
      "counterparty_account_number_ids_allowlist": [
        "account_number_3gUA5Tu6ITKoyAw8kefwyRofw4V"
      ]
    }
  },
  "instant_payment_controls": {
    "incoming": {
      "counterparty_filter": "accept_all",
      "counterparty_account_numbers_allowlist": []
    },
    "outgoing": {
      "counterparty_filter": "allowlist_only",
      "counterparty_account_numbers_allowlist": [
        {
          "account_number": "9876543210",
          "routing_number": "123456789"
        }
      ]
    }
  },
  "metadata": {},
  "created_at": "2026-10-07T15:02:11Z",
  "updated_at": "2026-10-09T18:25:03Z"
}
```

Every block is present in every status. The controls blocks always have a value, even the default. One field is conditional: `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.

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier, prefixed `account_number_`. |
| `account_number` | string | The account number counterparties use to reach this address. Lead generates it on `POST /v2/account_numbers`. You supply it on `POST /v2/account_numbers/register`. |
| `routing_number` | string | Lead's routing number. |
| `balance` | object | The balance this account number references. The [balance block](#the-balance-block) section on this page lists its fields. |
| `entity_id` | string | The entity that holds the account number. Required on create. Can't be changed. |
| `status` | enum | `active`, `inactive`, or `canceled`. See [Account Number Statuses](https://docs.lead.bank/v2/products/account-number/statuses.md). |
| `ach_controls` | object | Which ACH activity the account number accepts and sends, and which originator it sends under. See [Payment controls](https://docs.lead.bank/v2/products/account-number/controls.md). |
| `wire_controls` | object | Which wire counterparties the account number accepts and sends to. See [Payment controls](https://docs.lead.bank/v2/products/account-number/controls.md). |
| `internal_transfer_controls` | object | Which account numbers this one can transfer to and from. See [Payment controls](https://docs.lead.bank/v2/products/account-number/controls.md). |
| `instant_payment_controls` | object | Which instant payment counterparties the account number accepts and sends to. See [Payment controls](https://docs.lead.bank/v2/products/account-number/controls.md). |
| `metadata` | object | Key-value pairs for your own use. Lead doesn't read them. |
| `created_at`, `updated_at` | timestamp | RFC 3339, UTC. |

## The balance block

The table lists the fields in the balance block.

| Field | Type | Description |
| - | - | - |
| `type` | enum | `core_balance` or `user_deposit_balance`. |
| `id` | string | The ID of the balance. Prefixed `core_balance_` or `user_deposit_balance_` to match `type`. |

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.

```json theme={null}
{
  "id": "account_number_4hVB6Uv7JUKpzBx9lfgxzSpgx5W",
  "account_number": "123412349876",
  "routing_number": "123456789",
  "balance": {
    "type": "user_deposit_balance",
    "id": "user_deposit_balance_2xYw9Kn3Jp7QuS2lY5mAbC0dE4f"
  },
  "entity_id": "entity_3JrKd8Vb3NkXz6mYrT4wE1aQ7s",
  "status": "active",
  "ach_controls": {
```

`"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 with `PATCH`. The fields, the `counterparty_filter` values (`accept_all`, `allowlist_only`, `reject_all`), the allowlist fields, and the default behavior are documented on [Payment controls](https://docs.lead.bank/v2/products/account-number/controls.md).

`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](https://docs.lead.bank/v2/products/originators/originator-object.md).

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

| Field | Required | Description |
| - | - | - |
| `balance.type` | Yes | `core_balance` or `user_deposit_balance`. |
| `balance.id` | Yes | The balance the account number references. |
| `entity_id` | Yes | The entity that holds the account number. |
| `account_number` | Register only | The number you generated. |
| `ach_controls`, `wire_controls`, `internal_transfer_controls`, `instant_payment_controls` | No | Defaults accept all counterparties. |
| `metadata` | No | Key-value pairs for your own use. |

Lead checks the following before it creates the account number. Each failure returns 422.

| Condition | Result |
| - | - |
| `balance.id` is on an `attributed` or `shadow` core account, is a credit balance, or its core account doesn't allow you to create account numbers | `422`. The balance isn't eligible. |
| `balance.id` is a user deposit balance that settles outside Lead | `422`. The balance isn't eligible. |
| `balance.id` is held by Lead | `422`. The balance isn't eligible. Lead creates account numbers on its own balances. |
| `balance.id` isn't `active` | `422`. The balance isn't active. |
| `entity_id` is a `lead` entity, isn't eligible for `account_holder`, `minor_account_holder`, or `authorized_user`, or isn't an account holder or allowed actor on the account behind the balance | `422`. The entity isn't on the account. |
| `ach_controls.originator_id` names an originator whose `core_balance_id` isn't the account number's balance | `422`. The originator doesn't settle to this balance. |

## Listing account numbers

`GET /v2/account_numbers` returns a list (`objects`, `has_more`). Filter by any of:

| Filter | Matches |
| - | - |
| `balance_id` | Account numbers whose `balance.id` equals the value. |
| `entity_id` | Account numbers held by the entity. |
| `account_number` | The account number with that number. |

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.

| v1 | v2 | Notes |
| - | - | - |
| `POST /v1/account_number` | `POST /v2/account_numbers` | Resource name is plural. Applies to every sub-path. |
| `account_id` on create, response, and list filter | `balance: { type, id }` on create and response; `balance_id` list filter | Name the balance, not the account. `account_id` isn't accepted or returned. |
| `client_customer_id` or `entity_id`, optional | `entity_id`, required | `client_customer_id` isn't accepted or returned. |
| `unassigned` status | Removed | Every account number starts `active` with its entity bound. |
| `POST /v1/account_number/{id}/assign` | Removed | Entity is set on create. |
| `POST /v1/account_number/register` takes `account_id` | `POST /v2/account_numbers/register` takes `balance` and `entity_id` | Same requirements as create. |
| Errors in the v1 shape | Errors in the [v2 shape](https://docs.lead.bank/api-reference/using-the-api/errors-v2.md) | 422 conditions added on create and register. |

## Related

* [Account Number Overview](https://docs.lead.bank/v2/products/account-number/overview.md)
* [Account Number Statuses](https://docs.lead.bank/v2/products/account-number/statuses.md)
* [Payment controls](https://docs.lead.bank/v2/products/account-number/controls.md)
* [The Core Balance Object](https://docs.lead.bank/products/core-balance/core-balance-object.md)
* [The Entity Object](https://docs.lead.bank/v2/products/entity/entity-object.md)