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. If you are only trying to stop paying, note that an unpaid number suspends rather than releases, and reactivates on its own once the wallet can cover it.
Requires the admin 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.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/numbers/string"{ "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" }}Telecom circles that can be searched
The circle codes to pass as the region filter when searching.
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.