Tone docs
API referencePhone numbers

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.

Open in ClaudeOpen in ChatGPTView as Markdown

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

POST
/v1/numbers/purchase

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

Header Parameters

Idempotency-Key*string

REQUIRED. A unique key of your choosing — a UUID is fine. Retrying with the same key replays the first response instead of acting twice, which is what makes a timeout safe to retry here. Reusing a key with a DIFFERENT body is 422 idempotency_key_reused_with_different_params; retrying while the first is still running is 409 idempotency_key_in_use. Keys are remembered for 24 hours.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/numbers/purchase" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "agentId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "e164": "+918045678901",    "label": "Support line — Bengaluru"  }'
{  "data": {    "agentId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "capabilities": {      "sms": false,      "voice": true    },    "createdAt": "2026-08-25T09:14:22Z",    "currency": "INR",    "e164": "+918045678901",    "environment": "live",    "id": "4b7c1a02-9de5-4f31-bb07-2c1a5e9f0d43",    "inbound": "ready",    "label": "Support line — Bengaluru",    "mediaEndpoint": {      "authSecretId": "3f1a7f6e-2b4c-4d1e-9a8b-5c6d7e8f9a0b",      "customParameters": {        "tenant": "acme"      },      "format": "linear16",      "sampleRate": 16000,      "type": "static",      "url": "wss://media.acme.example/tone"    },    "nextRentalAt": "2026-09-01T06:30:00Z",    "numberType": "landline",    "provider": "exotel",    "purchasedAt": "2026-08-01T06:30:00Z",    "recordCalls": true,    "region": "KA",    "releasedAt": null,    "rentalPaise": 50000,    "routed": true,    "routingMode": "tone_agent",    "series": "regular",    "setupPaise": 50000,    "sipTrunk": {      "credentialId": "cred_5a1b",      "inboundTrunkId": "tin_2c7d",      "originationSipUri": "sip:acme@sip.livekit.cloud",      "originationUriId": "ouri_9f2c",      "outboundTrunkId": "tout_8e3f",      "provider": "vobiz",      "terminationDomain": "acme.sip.vobiz.example",      "terminationRealm": "vobiz.example",      "terminationUsername": "acme-out",      "transport": "tls"    },    "status": "pending"  }}
Was this page helpful?

Provision a SIP trunk pair for the customer's voice platform

Vobiz numbers only. Inbound calls are sent to sipUri; outbound termination credentials are returned ONCE in this response and never stored. The number switches to byo_sip.

Telecom circles that can be searched

The circle codes to pass as the region filter when searching.