# Release a number back to the carrier — permanent

Source: https://docs.usetone.ai/reference/numbers/release

> 🔴 There is no undo.

`DELETE /v1/numbers/{id}`
🔴 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.

## Parameters

| Name | In | | Meaning |
|---|---|---|---|
| `id` | path | required | The number's id. |

## Response

| Field | Type | | Meaning |
|---|---|---|---|
| `agentId` | string | null | required | The agent that answers calls TO this number. Null on BYO numbers. |
| `capabilities` | object | required | What the carrier says this number can carry. |
| `capabilities.sms` | boolean | optional | Whether the carrier reports SMS capability. Reported for completeness — Tone does not send SMS. |
| `capabilities.voice` | boolean | optional | Whether this number can carry calls. Every number Tone sells can. |
| `createdAt` | string | required | When you bought this number, RFC 3339 UTC. Also the rental anniversary the monthly charge falls on. |
| `currency` | string | required | Currency for the amounts on this number. INR today. |
| `e164` | string | required | E.164, with the country code and a leading `+`. |
| `environment` | string | required | `live` or `test`. |
| `id` | string | required | The number's id. Use it on every route that addresses this number. |
| `inbound` | string | required | Whether a call TO this number can actually be answered right now. `ready` — yes. `no_agent` — routed but nobody assigned. `no_endpoint` — a BYO number with no media endpoint. `unrouted` — no carrier flow, so nothing will ever arrive. |
| `label` | string | null | required | Your own name for it. |
| `mediaEndpoint` | object | null | required | Where call audio goes when this number routes to your own stack. Null unless routingMode is byo_ws. The endpoint credential is referenced by id, never returned here. |
| `nextRentalAt` | string | null | required | When the next month’s rental falls due. Null for sandbox numbers. |
| `numberType` | string | null | required | What kind of number this is. Open set — handle an unrecognised value rather than throwing. Today: `landline`, `mobile`, `tollfree`. |
| `provider` | string | required | Which carrier operates it. Open set — handle an unrecognised value rather than throwing. Today: `exotel`, `vobiz`, `sandbox`. |
| `purchasedAt` | string | null | required | When the number was bought. RFC 3339, UTC. |
| `recordCalls` | boolean | required | Per-number recording switch. It can only turn recording OFF — it never enables it where the platform has it disabled. |
| `region` | string | null | required | Telecom circle code, e.g. `KA`. |
| `releasedAt` | string | null | required | When the number was released back to the carrier. RFC 3339, UTC. Releasing is permanent — the number goes back into general inventory. |
| `rentalPaise` | integer | null | required | Monthly rental, in paise. |
| `routed` | boolean | required | Whether a carrier flow is attached, as far as our records go. For "can this take a call?", read `inbound` instead. |
| `routingMode` | string | required | Who answers the media: a Tone agent, your own WebSocket endpoint, or your SIP platform. Open set — handle an unrecognised value rather than throwing. Today: `tone_agent`, `byo_ws`, `byo_sip`. |
| `series` | string | required | Numbering series. Open set — handle an unrecognised value rather than throwing. Today: `regular`, `140`, `160`. |
| `setupPaise` | integer | null | required | One-off provisioning charge for this number, in paise. |
| `sipTrunk` | object | null | required | The provisioned SIP trunk pair, when this number routes to your own SIP platform. The termination password is shown once at provisioning and never again. |
| `status` | string | required | Lifecycle. `suspended` still HOLDS the number — unpaid rent is not a release — and it returns to `active` automatically once the wallet covers what is owed. Open set — handle an unrecognised value rather than throwing. Today: `pending`, `active`, `released`, `failed`, `suspended`. |

### Example response

```json
{
  "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"
  }
}
```