Turn phone calls on for a number

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.

POST
/v3/channels/voice

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v3/channels/voice" \  -H "Idempotency-Key: req_abc123_retry1" \  -H "Content-Type: application/json" \  -d '{    "number": "+12125550100",    "area_code": null,    "callback_url": "https://example.com/voice",    "default_for_app_calls": false,    "sandbox": false  }'
{
  "success": true,
  "data": {
    "callback_secret": "whsec_MWYyZDFlMmU2N2RmNmI3YThmNTZhODFiYzJlNGQzYjI=",
    "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"
  },
  "error": null,
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-06T09:10:22.6177412+00:00",
    "version": "v3"
  }
}
{
  "success": true,
  "data": {
    "number": "string",
    "status": "string",
    "default_for_app_calls": true,
    "callback_url": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "callback_secret": "string"
  },
  "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"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "BUSINESS_022",
    "message": "Phone number is not owned by this account",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-06T09:10:22.6177435+00:00",
    "version": "v3"
  }
}
Empty
Empty
{
  "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"
  }
}
{
  "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"
  }
}
{
  "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"
  }
}

Voice Callback Contract

Reference for the questions Sent POSTs to a voice number's callback URL and the answers your backend returns: the envelope, call.request and call.input, every action and instruction, parsing rules, account rules, and error reasons.

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