Tonedocs
API referencePhone numbers

Telecom circles that can be searched

The circle codes to pass as the region filter when searching — the circles at least one carrier Tone sells from has stock in, sorted by name. Pass provider for one carrier’s circles only.

Open in ClaudeOpen in ChatGPTView as Markdown

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

GET
/v1/numbers/regions

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

provider?string

Only this carrier — one of the provider values GET /v1/numbers/carriers lists. Omit to include every carrier Tone sells from. Naming a carrier that is not selling right now is a 422.

Value in

  • "exotel"
  • "voicelink"
  • "plivo"
  • "vobiz"
  • "sandbox"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/numbers/regions"
{  "data": [    {      "code": "KA",      "label": "Karnataka"    }  ]}
Was this page helpful?

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. Name the search result’s provider to buy from the carrier that listed it. Bind the number to an agent — with agentId here, or later with a PATCH — and it answers calls. Setup and the first period are debited immediately, at the carrier’s price: a month, or to the end of this month on a carrier that bills calendar months (the offer’s renewalCycle and renewsAt say which). Send the offer’s totalPaise back as confirmedTotalPaise and a price that moved since your customer saw it is a 409 price_changed rather than a charge they did not see.

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. Not paying ends the same way: an unpaid renewal is released at the deadline in releaseAt.