Tone docs
API referencePhone numbers

Carriers selling numbers right now

The carriers a search lists numbers from, in Tone’s order. Pass one’s provider to GET /v1/numbers/available or GET /v1/numbers/regions to see that carrier alone. A test key sees sandbox only, because test-mode numbers never come from a real carrier.

Requires the read scope. A key with less gets 403 insufficient_scope.

GET
/v1/numbers/carriers
AuthorizationBearer <token>

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/carriers"
{  "data": [    {      "label": "Plivo",      "provider": "plivo"    }  ]}
Was this page helpful?

Search every carrier for numbers available to buy (cursor-paginated)

Asks every carrier Tone sells from and lists their numbers together, cheapest first. Each result names its provider — pass it back when you buy, and the number is bought from and operated by that carrier. Pass provider here to list one carrier’s numbers only (GET /v1/numbers/carriers names them). If one carrier is unreachable the others still list; if nothing lists and a carrier failed, that failure is returned rather than an empty list. Page with meta.pagination.cursor, sending the same filters with it. 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 results while hasMore is still true. The first page carries meta.pagination.total, how many numbers the whole search lists, when every carrier searched can count it; it is the carriers’ own count where they page, so a walk can end a little short of it, and it is left out when a carrier cannot count a circle (VoiceLink) or failed. Live inventory, so results go stale — a number can be taken between this call and your purchase, which is a 409 number_unavailable, and a number sold between two pages can shift a carrier's listing by one. Only regular numbers are offered: the 140 and 160 series are not purchasable through any carrier API.

Remove the SIP trunk pair and return the number to tone_agent mode

Tears down the trunk. The number itself is kept — this is not a release.