> ## 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 Number Statuses

> Lifecycle of an account number, what each status means, which endpoint moves it, and how to observe changes.

You manage account number status. Every new account number starts `active`, and you move it with the activate, deactivate, and cancel endpoints. Lead can also deactivate an account number under its own policies.

## Lifecycle

The diagram shows every status and transition.

```mermaid theme={null}
flowchart LR
    active <--> inactive
    active --> canceled
    inactive --> canceled
```

## Statuses

The table lists each status.

| Status | Description | Notes |
| - | - | - |
| `active` | The account number can receive payments and, where its controls allow, send them. | Every new account number starts here. |
| `inactive` | The account number is paused. It can't send or receive. | Use this when you expect the account number to return to `active`. You can still update controls and metadata with `PATCH`. |
| `canceled` | The account number is permanently closed. You can't undo this. | The number isn't reused. The account number stays readable. |

## Transitions

The table lists which endpoint makes each transition.

| Endpoint | From | To |
| - | - | - |
| `POST /v2/account_numbers/{account_number_id}/deactivate` | `active` | `inactive` |
| `POST /v2/account_numbers/{account_number_id}/activate` | `inactive` | `active` |
| `POST /v2/account_numbers/{account_number_id}/cancel` | `active` or `inactive` | `canceled` |

The three endpoints take no request body but require an `Idempotency-Key`. Here's what they do when the account number is already in that status, or can't reach it:

* Calling `/deactivate` on an `inactive` account number, or `/cancel` on a `canceled` one, returns `200` with the current object.
* Calling `/activate` on a `canceled` account number returns an error. A canceled account number can't be reused.

You can't change status with PATCH.

## What a status means for payments

Status affects payments as follows:

* **Incoming.** Only an `active` account number receives. Lead returns or rejects payments addressed to an `inactive` or `canceled` account number on each rail's normal path.
* **Outgoing.** Only an `active` account number sends. Lead rejects a payment request that names an `inactive` or `canceled` account number.
* **Status doesn't cascade.** Changing the status of the core balance or user deposit balance behind an account number doesn't change the account number's status. Lead rejects payments on the balance instead.

## Observing changes

You can learn about changes these ways:

* **`account_number.created` webhook.** Sent when Lead creates an account number on your program. Account numbers you create return synchronously and don't emit it.
* **No status webhooks.** Activate, deactivate, and cancel return the updated object in the response. [Webhooks & Events](https://docs.lead.bank/api-reference/using-the-api/webhooks.md) lists the matching events as not sent.
* **Polling.** `GET /v2/account_numbers/{account_number_id}` returns the current status.

## Related

* [The Account Number Object](https://docs.lead.bank/v2/products/account-number/account-number-object.md)
* [Account Number Overview](https://docs.lead.bank/v2/products/account-number/overview.md)
* [Core Balance Statuses](https://docs.lead.bank/products/core-balance/statuses.md)
* [Webhooks & Events](https://docs.lead.bank/api-reference/using-the-api/webhooks.md)