# Number lifecycle

Source: https://docs.usetone.ai/flows/number-lifecycle

> Search, buy, route, renew, suspend, reactivate, release — and which of those are reversible.

| State | Meaning | Reversible |
|---|---|---|
| `pending` | Bought; the carrier has not finished provisioning | — |
| `active` | Working in both directions | — |
| `suspended` | Unpaid rent. Refuses calls, **keeps your claim on the number** | Yes — top up |
| `released` | Returned to carrier inventory | 🔴 **No** |
| `failed` | Provisioning did not complete | — |

## Buying

```bash
curl -H "Authorization: Bearer $TONE_KEY" "$TONE_API/v1/numbers/eligibility"
curl -H "Authorization: Bearer $TONE_KEY" "$TONE_API/v1/numbers/available?region=KA"
curl "$TONE_API/v1/numbers/purchase" -X POST \
  -H "Authorization: Bearer $TONE_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H 'content-type: application/json' -d '{"e164":"+918045678901"}'
```

Inventory is live. A number taken between your search and your purchase is a
`409 number_unavailable` — search again.

The number arrives **unrouted**. Bind an agent, or set a BYO endpoint, before it
can do anything.

## The monthly anniversary

Purchase debits setup plus the first month and sets `nextRentalAt` one month out.
Anniversaries clamp at month end: bought on 31 January, it renews 28 February and
stays on the 28th.

## When rent cannot be paid

| Day | What happens | Event |
|---|---|---|
| Anniversary | Debit fails; grace period starts; owners and admins emailed | — |
| Past grace | Number **suspended** — refuses calls both ways | `number.suspended` |
| Wallet topped up | **Reactivates automatically** | `number.reactivated` |

🔴 Suspension is not release. The number is still yours, still costs the overdue
rent, and comes back on its own. Freeing it would sell your published line to a
stranger.

## Releasing

```bash
curl "$TONE_API/v1/numbers/$NUMBER" -X DELETE -H "Authorization: Bearer $TONE_KEY"
```

Permanent, immediate and unrecoverable. If your goal is to stop paying, do
nothing — non-payment suspends, and suspension reverses.

## Changing who answers

```bash
curl "$TONE_API/v1/numbers/$NUMBER" -X PATCH \
  -H "Authorization: Bearer $TONE_KEY" -H 'content-type: application/json' \
  -d '{"routingMode":"byo_ws","mediaEndpoint":{"type":"static","url":"wss://media.example.com/tone"}}'
```

Switching modes keeps the bound agent (ignored while BYO, restored on switching
back) and never reprices history — each call snapshots its own mode.