---
title: "Get one voice number"
method: GET
path: "/v3/channels/voice/{number}"
tags: ["Channels", "Voice"]
---

# Get one voice number

`GET /v3/channels/voice/{number}`

## Request

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

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

## Path parameters

- `number` string, required

## Headers

- `x-profile-id` string, uuid

## Response `200`

The voice number

- SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceNumberState: Standard API response envelope for all v3 endpoints
  - `success` boolean: Indicates whether the request was successful
  - `data` SentDmServicesCommonChannelsContractsVoiceNumberState: One number the profile carries phone calls on.
    - `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

- `400`: The number is not a phone number
- `401`: Unauthorized - Invalid API credentials
- `403`: Forbidden
- `404`: This account has no voice number for that number
- `500`: Internal server error

## Changes

- **2026-10-28** `41acb2ceb84d`: 2 info
  - added the optional property `data/allOf[#/components/schemas/SentDmServicesCommonChannelsContractsVoiceNumberState]/agent_id` to the response with the `200` status
  - added the optional property `data/allOf[#/components/schemas/SentDmServicesCommonChannelsContractsVoiceNumberState]/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/:number/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)