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
| Body | Effect |
|---|---|
"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": true | makes 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 and the status are kept |
"agent_id": "agent_…" | one of your voice agents answers calls to the number, within about an hour of the change (the provider applies the move on its own clock, and routes_to reads agent as soon as it has recorded it); it wins over callback_url for calls to the number, and calls your app places from it still follow your app. routes_to reads agent_pending while the number is still being moved to the agent |
"agent_id": null | unbinds the agent, so callback_url answers calls to the number again |
| key omitted | left 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. agent_id is applied first, so a refusal to move the number to or from the agent leaves everything as it was, and the 409 and 400 refusals below are decided before anything is written, so they leave everything as it was too. A body that names none of them is refused.
A number can be on without a callback URL: calls placed from your app then connect straight to the number or user they dial, and calls to the number are declined.
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 you never turned voice on for is 404, and so is an agent_id that is not one of your agents. Add the number with POST /v3/channels/voice.
502 means the number could not be moved to or from the agent, or an agent_id was sent while numbers cannot be bound to agents; nothing was written.
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.
number*stringThe number in E.164 format with the plus sign URL-encoded, e.g. %2B12125550100
Idempotency-Key?stringUnique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.
^[a-zA-Z0-9_-]+$length <= 255x-profile-id?stringProfile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.
uuidapplication/json- body
Changes one of your voice numbers: turns it on or off, makes it the default line for app calls, replaces its callback URL, or binds it to one of your voice agents.
Partial. An omitted field is left alone, so one field can be corrected without restating the others. A body that names none of them is refused rather than answered 200 for a write that did not happen.
sandbox?booleanSandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution
status?|ACTIVE turns calls on for the number again, INACTIVE turns them off. Matched ignoring case. Turning the default line off is refused while other active voice numbers remain.
"ACTIVE""INACTIVE"default_for_app_calls?|true makes this the line app-originated calls are placed from when a voice token names no number. false is refused: an account with active voice numbers always has exactly one default, so the default moves by giving it to another number.
callback_url?|A new callback URL for the number, active or not: an absolute HTTP or HTTPS URL on a public host, where Sent asks what to do with each call. The signing secret is kept.
agent_id?|One of your voice agents, such as agent_9f2ab000-0000-4000-8000-000000000001, to answer calls to the number, or null to unbind it so the callback URL answers them again. The agent wins over callback_url for calls to the number; calls your app places from it still follow your app.
The voice number as stored
application/json- response
Standard API response envelope for all v3 endpoints
success?booleanIndicates whether the request was successful
data?|nullThe response data (null if error)
error?|nullError details (null if successful)
meta?Metadata about the request and response
curl -X PATCH 'https://api.sent.dm/v3/channels/voice/string' \ -H 'Idempotency-Key: req_abc123_retry1' \ -H 'Content-Type: application/json' \ -d '{ "number": "+12125550100", "callback_url": "https://example.com/voice", "default_for_app_calls": true}'{ "success": true, "data": { "number": "+12125550100", "status": "ACTIVE", "default_for_app_calls": true, "callback_url": "https://example.com/voice", "agent_id": null, "routes_to": "callback", "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" }}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.