---
title: "List your voice numbers"
method: GET
path: "/v3/channels/voice"
tags: ["Channels", "Voice"]
---

# List your voice numbers

`GET /v3/channels/voice`

## Request

- Base URL: `https://api.sent.dm`
- URL: `https://api.sent.dm/v3/channels/voice`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

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}`.

## Headers

- `x-profile-id` string, uuid

## Response `200`

Your voice numbers

- SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfListOfVoiceNumberState: Standard API response envelope for all v3 endpoints
  - `success` boolean: Indicates whether the request was successful
  - `data` SentDmServicesCommonChannelsContractsVoiceNumberState[], nullable: The response data (null if error)
    - `number` string: The number, in E.164.
    - `status` string: ACTIVE while the number carries calls, INACTIVE once it was turned off. Nothing provisions: a number the customer holds can carry calls the moment voice is turned on for it.
    - `default_for_app_calls` boolean: Whether this is the line app-originated calls are placed from when a voice token names no number. Exactly one active voice number carries it while the profile has any.
    - `callback_url` string, nullable: Where Sent asks what to do with each call on this number: a signed question is POSTed here when a call arrives or a caller presses a key, and the answer decides the call. The signing secret is not on this read; it is shown when voice is turned on and by the rotate endpoint.
    - `agent_id` string, nullable: The voice agent calls to this number go to, such as agent_9f2ab000-0000-4000-8000-000000000001. It wins over callback_url for calls to the number; calls your app places from the number still follow your app. Null when no agent answers the number.
    - `routes_to` string: Who answers calls to this number: agent, the voice agent in agent_id; agent_pending, that agent once the number has finished moving to it, with calls possibly unanswered until then; callback, your callback_url; or none, in which case calls to it are declined.
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `error` SentDmServicesEndpointsCustomerAPIv3SharedApiError: Error information
    - `code` string: Machine-readable error code (e.g., "RESOURCE_001")
    - `message` string: Human-readable error message
    - `details` object, nullable: Additional validation error details (field-level errors)
    - `doc_url` string, nullable: URL to documentation about this error
  - `meta` SentDmServicesEndpointsCustomerAPIv3SharedApiMeta: Request and response metadata
    - `request_id` string: Unique identifier for this request (for tracing and support)
    - `timestamp` string, date-time: Server timestamp when the response was generated
    - `version` string: API version used for this request

## Other responses

- `401`: Unauthorized - Invalid API credentials
- `403`: Forbidden
- `500`: Internal server error

## Changes

- **2026-10-28** `41acb2ceb84d`: 2 info
  - added the optional property `data/items/agent_id` to the response with the `200` status
  - added the optional property `data/items/routes_to` to the response with the `200` status
- **2026-10-16** `6c829543a93e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/changes/v3/channels/voice/get.md)

---

[API](https://skmtc.dev/sentdm/apis/sent-dm-api-v3.md) - [All operations](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/revisions/bdcca958cac7?raw)