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