Phone numbers

A number is the only part of Tone that costs money whether or not you use it, and the only part that renews every month. 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","provider":"exotel","confirmedTotalPaise":49900,"label":"Support line"}'

Search asks every carrier Tone sells from at once and lists their numbers together, cheapest first. Each result names its provider, and its price is that carrier's own. Send the same provider when you buy: the number is bought from that carrier and runs on it from then on. One organization can hold numbers from several.

⚠️ An Exotel mobile number shows the people it calls a landline number as the caller ID, not the mobile number itself.

To see one carrier's numbers only, pass provider to the search. GET /v1/numbers/carriers lists the carriers selling right now, and GET /v1/numbers/regions?provider=… lists that carrier's circles. Naming a carrier that is not selling is a 422, never an empty list:

curl -H "Authorization: Bearer $TONE_KEY" "$TONE_API/v1/numbers/carriers"

curl -H "Authorization: Bearer $TONE_KEY" \
  "$TONE_API/v1/numbers/available?number_type=landline&provider=plivo"

Every number listed for a region is known to be in that circle. VoiceLink's stock carries no circle, so each of its numbers is looked up, and one whose circle cannot be determined is left out of a region search — leave region out to see every carrier's stock. GET /v1/numbers/regions lists the circles at least one carrier has stock in. If one carrier is unreachable the others still list; if nothing lists and a carrier failed, you get that carrier's error rather than an empty list, so an empty list always means there was nothing to sell.

Results come a page at a time — limit per page, 20 by default and at most 50. To see more, send meta.pagination.cursor back as cursor with the same filters; a cursor sent with a different number_type, region, contains, sms or provider is a 400, because it describes a position in a different search:

curl -H "Authorization: Bearer $TONE_KEY" \
  "$TONE_API/v1/numbers/available?number_type=landline&region=KA&cursor=$CURSOR"

Every page is sorted cheapest first. Carriers are read a page at a time, so a later page can occasionally hold a cheaper number than an earlier one, and a page can hold fewer than limit numbers while hasMore is still true — keep going until hasMore is false.

The first page also carries meta.pagination.total, how many numbers the whole search lists, when every carrier searched can count it. Where a carrier pages, the count is its own, so a walk can end a few numbers short of it. It is left out when a carrier cannot count what the search lists — VoiceLink cannot count by circle, so a region search that includes VoiceLink has no total — and when a carrier failed.

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

Show your customer what they are buying before you buy it: each offer's totalPaise is what the purchase charges now, renewsAt is when that runs out, and rentalPaise is what every month after costs (see Rent). Then send totalPaise back as confirmedTotalPaise. The purchase re-prices the number with its carrier and charges that, never your figure; if the carrier's price has moved since, the purchase is a 409 price_changed, with nothing reserved or charged, rather than a charge your customer never saw.

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

A number costs exactly what its carrier quotes. Purchase debits the first period (plus a setup fee only if the carrier charges one), and renewalCycle says how the periods after it run:

A day before each renewal (nextRentalAt on the number) the next month is charged. Anniversaries clamp at month end, so a number bought on 31 January renews on 28 February and stays on the 28th thereafter.

⚠️ A VoiceLink number's first period is short, at the full price. VoiceLink runs every number to the end of the month it was bought in and does not prorate, so the first payment buys the rest of that month: bought on 12 October, 20 days; bought on the evening of 31 October, a few hours, with November's rent taken the same day. Every renewal after it, on the 1st, buys a whole month. The offer's renewsAt is the end of the first period, so you can show your customer exactly that before they buy. VoiceLink numbers bought before this change (changelog) keep renewing on the day they were bought.

If the wallet cannot cover the renewal:

1. Owners and admins are emailed, the number's releaseAt is set six hours out, and number.renewal_due fires.
2. Add money before releaseAt and the number renews on its own within minutes.
3. Otherwise the number is released, and number.released fires.

🔴 An unpaid renewal ends in release, and release is permanent. The number goes back to its carrier and anyone can buy it. Subscribe to wallet.balance.low and number.renewal_due, or keep your balance above a month's rent.

Why a number is suspended

Unpaid rent used to suspend a number rather than release it, and a number that went unpaid then can still show suspended. It refuses calls in both directions but keeps your claim on the line, and it gets the same warning as any unpaid renewal: add money before its releaseAt and it renews within minutes, firing number.reactivated. Otherwise it is released, and number.released fires.

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. Not paying ends the same way: an unpaid renewal is released six hours after the warning.

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.

To get one, ask from the dashboard: Numbers → Request a number, beside the 140 and 160 series. Our team arranges each one with the carrier and emails you the answer. Your business has to be verified first, and your DLT Principal Entity ID submitted on the Compliance page. It can still be awaiting approval when you ask. TRAI keeps the 160 series for businesses regulated by RBI, SEBI, IRDAI or PFRDA, and for government.