# Point a number at the inbound flow, or unroute it

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

> Repairs routing for numbers bought before inbound existed, or after a dev tunnel changed hostname.

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

Requires the `write` scope.

## Parameters

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

## Request body

| Field | Type | | Meaning |
|---|---|---|---|
| `enabled` | boolean | required | Whether this number should accept inbound calls. Turning it off makes the number refuse inbound while keeping the number, its rental and its agent binding intact. |

### Example request

```json
{
  "enabled": true
}
```

## 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"
  }
}
```