Tone docs
API referencePhone numbers

Search the carrier for numbers available to buy

Live carrier inventory, so results go stale — a number can be taken between this call and your purchase, which is a 409 number_unavailable. Only regular numbers are offered: the 140 and 160 series are not purchasable through any carrier API.

Open in ClaudeOpen in ChatGPTView as Markdown

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

GET
/v1/numbers/available

Authorization

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

Query Parameters

number_type?string

Which kind of number to search for. Open set — handle an unrecognised value rather than throwing. Today: landline, mobile, tollfree.

Default"landline"

Value in

  • "landline"
  • "mobile"
  • "tollfree"
region?string

Telecom circle code, uppercase — list them with GET /v1/numbers/regions. Omit to search the carrier default pool.

Match^[A-Z]+$
Length2 <= length <= 4
contains?string

Digits the number must contain. Digits only — carriers treat other characters inconsistently.

Match^\d{1,10}$
sms?string

Only numbers that can also send SMS. Note that SMS itself additionally requires DLT registration.

Value in

  • "0"
  • "1"
  • "true"
  • "false"
limit?integer

How many results to return. 1-50, defaulting to 20.

Range1 <= value <= 50
Default20

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/numbers/available"
{  "data": [    {      "capabilities": {        "sms": false,        "voice": true      },      "e164": "+918045678901",      "numberType": "landline",      "region": "KA",      "rentalPaise": 0,      "setupPaise": 0,      "totalPaise": 0    }  ]}
Was this page helpful?

Assign a sandbox number — 140/160 require an approved DLT PE ID

Allocates a free number from the sandbox pool. No carrier is contacted and nothing is charged — this is the number you build against before any paperwork exists.

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.