Get one voice number

Reads one of your voice numbers, active or inactive: its status, whether it is the default line for calls placed from your app, and its callback URL. The signing secret is not on this read.

The same shape GET /v3/channels/voice lists, and the same shape PATCH on this path accepts and returns, so what comes back can be sent back.

The number is the E.164 value in the path with the plus sign URL-encoded (%2B).

GET

/v3/channels/voice/{number}

Path Parameters

number*string

The number in E.164 format with the plus sign URL-encoded, e.g. %2B12125550100

Header Parameters

Response Body

The voice number

application/json

response

Standard API response envelope for all v3 endpoints

success?boolean

Indicates whether the request was successful

data?|null

The response data (null if error)

error?|null

Error details (null if successful)

meta?

Metadata about the request and response

Example Request

curl -X GET 'https://api.sent.dm/v3/channels/voice/+12125550100'

Example ResponseSchema

{  "success": true,  "data": {    "number": "+12125550100",    "status": "ACTIVE",    "default_for_app_calls": true,    "callback_url": "https://example.com/voice",    "agent_id": null,    "routes_to": "none",    "created_at": "2026-07-22T12:00:00+00:00",    "updated_at": "2026-07-22T12:00:00+00:00"  },  "meta": {    "request_id": "req_8H3jNq5sWx",    "timestamp": "2026-07-22T12:00:00+00:00",    "version": "v3"  }}

List your voice numbers GET

Every number you turned phone calls on for, active or inactive, oldest first. Each entry carries the number's status, whether it is the default line for calls placed from your app, and its callback URL. The signing secret is never on a read; it is shown when voice is turned on and by `POST /v3/channels/voice/{number}/rotate-secret`. The same entries `GET /v3/channels` reports under `voice`, and the same shape `GET /v3/channels/voice/{number}` returns for one of them. Change a number with `PATCH /v3/channels/voice/{number}`.

Change one voice number PATCH

Changes one of your voice numbers and answers with the number as stored, the same shape `GET` on this path returns, so what comes back can be sent back. ## What it changes | Body | Effect | | --- | --- | | `"status": "ACTIVE"` | turns calls on again for a number you turned off; the callback URL and the secret it had are kept | | `"status": "INACTIVE"` | turns calls off; the callback URL and the secret stay on the number | | `"default_for_app_calls": true` | makes this the line app-originated calls are placed from when a voice token names no number | | `"callback_url": "https://example.com/voice"` | replaces where Sent asks what to do with each call on the number; the signing secret and the status are kept | | `"agent_id": "agent_…"` | one of your voice agents answers calls to the number, within about an hour of the change (the provider applies the move on its own clock, and `routes_to` reads `agent` as soon as it has recorded it); it wins over `callback_url` for calls to the number, and calls your app places from it still follow your app. `routes_to` reads `agent_pending` while the number is still being moved to the agent | | `"agent_id": null` | unbinds the agent, so `callback_url` answers calls to the number again | | key omitted | left exactly as it is | `status` is matched ignoring case. Any combination is accepted: `status: "ACTIVE"` with `default_for_app_calls: true` turns a number on as the new default, and a `callback_url` sent with either status is written too. `agent_id` is applied first, so a refusal to move the number to or from the agent leaves everything as it was, and the `409` and `400` refusals below are decided before anything is written, so they leave everything as it was too. A body that names none of them is refused. A number can be on without a callback URL: calls placed from your app then connect straight to the number or user they dial, and calls to the number are declined. ## What it will refuse **`default_for_app_calls: false` is `400`.** An account with active voice numbers always has exactly one default, so the default moves by giving it to another number. **Turning the default line off is `409`** while other active voice numbers remain. Move the default to another number first. Turning off your last voice number is allowed; that turns phone calls off. **Making an inactive number the default is `400`.** Send `status: "ACTIVE"` in the same call. **A number you never turned voice on for is `404`**, and so is an `agent_id` that is not one of your agents. Add the number with `POST /v3/channels/voice`. **`502` means the number could not be moved to or from the agent**, or an `agent_id` was sent while numbers cannot be bound to agents; nothing was written. The number is the E.164 value in the path with the plus sign URL-encoded (`%2B`). With `sandbox: true` nothing is written: the request is validated against the stored number and the number is reported with `200` as it would read after the change.

{
  "success": true,
  "data": {
    "number": "+12125550100",
    "status": "ACTIVE",
    "default_for_app_calls": true,
    "callback_url": "https://example.com/voice",
    "agent_id": null,
    "routes_to": "none",
    "created_at": "2026-07-22T12:00:00+00:00",
    "updated_at": "2026-07-22T12:00:00+00:00"
  },
  "meta": {
    "request_id": "req_8H3jNq5sWx",
    "timestamp": "2026-07-22T12:00:00+00:00",
    "version": "v3"
  }
}