Telecom circles that can be searched
The circle codes to pass as the region filter when searching.
Requires the read scope. A key with less gets 403 insufficient_scope.
Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.
In: header
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/numbers/regions"{ "data": [ { "code": "KA", "label": "Karnataka" } ]}Buy a number — requires completed business verification and an Idempotency-Key
🔴 Idempotency-Key is REQUIRED — without it this returns 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. The number arrives unrouted; bind it to an agent with a PATCH. Setup and the first month are debited immediately.
Release a number back to the carrier — permanent
🔴 There is no undo. The number returns to general inventory and can be bought by anyone. Rental stops. If you are only trying to stop paying, note that an unpaid number suspends rather than releases, and reactivates on its own once the wallet can cover it.