Number lifecycle
Search, buy, route, renew, 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, from before renewals ended in release. Refuses calls | Yes — add money before its releaseAt |
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","provider":"exotel"}'Search lists every carrier Tone sells from together, cheapest first, and each result
names its provider. Buy with that provider and the number is bought from — and
run by — that carrier.
Inventory is live. A number taken between your search and your purchase is a
409 number_unavailable — search again.
The number arrives with nobody to answer it. Bind an agent, or set a BYO endpoint, before it can do anything.
The monthly anniversary
Purchase debits the first month — plus a setup fee only if the carrier charges one
— and sets nextRentalAt one month out. A day before each anniversary the next
month is charged. Anniversaries clamp at month end: bought on 31 January, it renews
28 February and stays on the 28th.
When rent cannot be paid
| When | What happens | Event |
|---|---|---|
| A day before the anniversary | Debit fails; owners and admins emailed; releaseAt set six hours out | number.renewal_due |
Money added before releaseAt | Renews automatically, within minutes | — |
releaseAt passes, still unpaid | Number released at its carrier | number.released |
🔴 An unpaid renewal ends in release, and release is permanent — the number goes back to its carrier and anyone can buy it. The release happens before the carrier's own renewal date, so nobody is billed for a month nobody uses.
Releasing
curl "$TONE_API/v1/numbers/$NUMBER" -X DELETE -H "Authorization: Bearer $TONE_KEY"Permanent, immediate and unrecoverable. Not paying ends the same way: an unpaid renewal is released six hours after its warning.
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.