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.
Requires the write scope. A key with less gets 403 insufficient_scope.
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
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 PATCH "https://example.com/v1/numbers/string" \ -H "Content-Type: application/json" \ -d '{ "agentId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451", "label": "Support line — Bengaluru", "mediaEndpoint": { "authSecretId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451", "customParameters": { "tenant": "acme" }, "format": "linear16", "sampleRate": 16000, "type": "static", "url": "wss://media.example.com/tone" }, "recordCalls": true, "routingMode": "tone_agent" }'{ "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" }}Point a number at the inbound flow, or unroute it
Repairs routing for numbers bought before inbound existed, or after a dev tunnel changed hostname. Talks to the carrier, so it is a POST rather than part of PATCH — rebinding an agent must not fail during a carrier outage.
Place an outbound call (runs the compliance gate)
Runs the full pre-dial compliance gate inside the same transaction, so a refusal is a 403 with the audit rows already written and no carrier contacted. Requires agentId on a number that routes to a Tone agent and forbids it on a BYO number. Over your concurrent-call quota this returns 429 BEFORE the gate runs, so no verdict is recorded. Send an Idempotency-Key — a timeout is otherwise indistinguishable from a call you did not place.