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}

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v3/channels/voice/+12125550100"
{
  "success": true,
  "data": {
    "number": "+12125550100",
    "status": "ACTIVE",
    "default_for_app_calls": true,
    "callback_url": "https://example.com/voice",
    "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"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_001",
    "message": "'number' must be a valid phone number in E.164 format (e.g. +14155551234)",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_8H3jNq5sWx",
    "timestamp": "2026-07-22T12:00:00+00:00",
    "version": "v3"
  }
}
Empty
Empty
{
  "success": false,
  "data": null,
  "error": {
    "code": "RESOURCE_013",
    "message": "This account has no voice number +12125550100",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_8H3jNq5sWx",
    "timestamp": "2026-07-22T12:00:00+00:00",
    "version": "v3"
  }
}
{
  "success": true,
  "error": {
    "code": "string",
    "message": "string",
    "details": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "doc_url": "string"
  },
  "meta": {
    "request_id": "string",
    "timestamp": "2019-08-24T14:15:22Z",
    "version": "string"
  }
}

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 is kept, and a number that was waiting for its first URL is turned on | | 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. A body that names none of the three is refused. ## 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 added without a `callback_url` is `INACTIVE` for that one reason, so sending it a `callback_url` turns it on by itself, and it becomes your default line if you have no other active voice number. A number you turned off while it had a URL stays off. **A number you never turned voice on for is `404`.** Add it with `POST /v3/channels/voice`. 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.