Phone numbers

A number is the only part of Tone that costs money whether or not you use it, and the only part with a monthly anniversary. That shapes most of its behaviour.

Getting one

In test mode a number is free and instant, and no carrier is contacted:

curl "$TONE_API/v1/numbers" -X POST \
  -H "Authorization: Bearer $TONE_KEY" -H 'content-type: application/json' \
  -d '{"series":"regular"}'

In live mode you search real carrier inventory and buy:

curl -H "Authorization: Bearer $TONE_KEY" \
  "$TONE_API/v1/numbers/available?number_type=landline&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","label":"Support line"}'

🔴 Idempotency-Key is required here. Without it you get a 400. A duplicate purchase buys a second number and starts a second monthly rental, and a timeout is indistinguishable from a purchase that never happened — so retry with the same key. See Idempotency.

Buying needs completed business verification. GET /v1/numbers/eligibility answers before you try.

Inventory is live, so results go stale: a number taken between your search and your purchase is a 409 number_unavailable. Search again and pick another.

Who answers it

routingMode decides that, per number — one organization can mix all three.

curl "$TONE_API/v1/numbers/$NUMBER" -X PATCH \
  -H "Authorization: Bearer $TONE_KEY" -H 'content-type: application/json' \
  -d "{\"agentId\":\"$AGENT\"}"

Switching to a BYO mode keeps the bound agent — it is ignored while BYO and restored when you switch back. Switching mode never reprices past calls: each call snapshots its own mode at creation.

⚠️ A byo_sip number is not dialable through POST /v1/calls; the platform reaches the carrier directly, so there is no pre-dial hook. Use the verdict API as your pre-flight instead.

Rent, and what happens when you stop paying

Purchase debits setup plus the first month and sets an anniversary. On each anniversary the rental is debited. Anniversaries clamp at month end, so a number bought on 31 January renews on 28 February and stays on the 28th thereafter.

If the wallet cannot cover it:

1. A grace period starts, with an email to owners and admins on day one.
2. Past grace the number is suspended — it refuses calls in both directions and emits number.suspended.
3. Top up, and it reactivates on its own, emitting number.reactivated.

🔴 A suspended number keeps your claim on the line. Unpaid rent is not a release: freeing the number would sell your published phone number to a stranger.

Releasing

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

🔴 Permanent. The number returns to general carrier inventory and anyone can buy it. If you only want to stop paying, note that not paying suspends rather than releases, and reverses itself.

The 140 and 160 series

140 (telemarketing) and 160 (transactional, BFSI) exist in the regulations and in NUMBER_SERIES, and both require an approved DLT Principal Entity ID. Neither is purchasable through a carrier API today — search and purchase only ever offer regular numbers. We would rather say so than show you a Buy button that cannot work.