Change one voice number

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

BodyEffect
"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": truemakes 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 omittedleft 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.

PATCH
/v3/channels/voice/{number}

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

curl -X PATCH "https://example.com/v3/channels/voice/+12125550100" \  -H "Idempotency-Key: req_abc123_retry1" \  -H "Content-Type: application/json" \  -d '{    "default_for_app_calls": true,    "callback_url": "https://example.com/voice",    "sandbox": false  }'
{
  "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-08-01T16:45:00+00:00"
  },
  "meta": {
    "request_id": "req_2D6gPt4vYz",
    "timestamp": "2026-08-01T16:45:00+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_001",
    "message": "Supply at least one of status, default_for_app_calls or callback_url",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_2D6gPt4vYz",
    "timestamp": "2026-08-01T16:45: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_2D6gPt4vYz",
    "timestamp": "2026-08-01T16:45:00+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "CONFLICT_007",
    "message": "This number is the default line for app calls and other voice numbers are active; move the default to another number first",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_2D6gPt4vYz",
    "timestamp": "2026-08-01T16:45: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"
  }
}

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

Rotate a voice number's callback secret POST

Generates a new signing secret for the questions Sent sends to this number's callback URL and returns it. The previous secret stops signing immediately, so update your backend before the next call reaches it. The number is the E.164 value in the path with the plus sign URL-encoded (`%2B`). With `sandbox: true` a secret is generated and returned with `202`, and nothing is written.