Tonedocs
API referencePhone numbers

Switch inbound calling on or off for a number

Off refuses inbound calls on this number and leaves everything else alone — the number, its rental, its agent binding, and outbound dialling. On also repairs the carrier-side routing, which is what makes this the recovery path for a number bought before inbound existed, or after a dev tunnel changed hostname. Switching on talks to the carrier, so it is a POST rather than part of PATCH — rebinding an agent must not fail during a carrier outage.

Open in ClaudeOpen in ChatGPTView as Markdown

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

POST
/v1/numbers/{id}/routing

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

Path Parameters

id*string

The number's id.

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

application/json

curl -X POST "https://example.com/v1/numbers/string/routing" \  -H "Content-Type: application/json" \  -d '{    "enabled": true  }'
{  "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",    "releaseAt": null,    "releasedAt": null,    "renewalCycle": "anniversary",    "rentalPaise": 50000,    "routed": true,    "routingMode": "tone_agent",    "series": "regular",    "setupPaise": 0,    "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"    },    "sipTrunkId": null,    "status": "pending"  }}
Was this page helpful?

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.

Rename a number or bind it to an agent

Also where you switch who answers it. Send null to clear a field; omit the key to leave it alone. Switching to a BYO routing mode KEEPS the bound agent — it is ignored while BYO and restored when you switch back. byo_ws needs a mediaEndpoint in the same request unless one is already stored (422 otherwise), and byo_sip is set and cleared only by POST/DELETE /v1/numbers/{id}/sip (409 here).