List your voice numbers
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}.
Response Body
application/json
application/json
curl -X GET "https://example.com/v3/channels/voice"{
"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"
},
{
"number": "+12125550101",
"status": "INACTIVE",
"default_for_app_calls": false,
"callback_url": "https://example.com/voice-support",
"created_at": "2026-07-23T09:30:00+00:00",
"updated_at": "2026-08-01T16:45:00+00:00"
}
],
"meta": {
"request_id": "req_5V2kLm8nQr",
"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"
}
}Turn phone calls on for a number POST
Adds voice to one of the numbers you hold, or gives you a new one. Send `number` for a number that is already yours (see `GET /v3/channels`); leave it out to be given a new US number, optionally in a particular `area_code`. Sending both is refused. Nothing registers, so the number can carry calls as soon as this returns. What happens on a call is decided by your `callback_url`: when a call arrives on the number, or a caller presses a key on a menu, Sent POSTs a signed question there and follows the answer. The response carries the `callback_secret` the questions are signed with, the one time it is shown without rotating; verify a question the way you verify a webhook. `POST /v3/channels/voice/{number}/test` sends a test question and reports the verdict. Your first voice number becomes the line app-originated calls are placed from when a voice token names no number; send `default_for_app_calls: true` to give that role to another number. A number you turned off earlier is turned back on, and the same number with a different `callback_url` has its URL replaced and keeps its secret. Read the number's settings with `GET /v3/channels/voice` and change them with `PATCH /v3/channels/voice/{number}`. With `sandbox: true` the request is validated and a simulated number reported with `202`; nothing is written and no number is bought.
Get one voice number GET
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`).