--- title: "Change one voice number" method: PATCH path: "/v3/channels/voice/{number}" tags: ["Channels", "Voice"] --- # Change one voice number `PATCH /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 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. ## Path parameters - `number` string, required ## Headers - `Idempotency-Key` string - `x-profile-id` string, uuid ## Request body - SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsPatchVoiceChannelRequest: 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` boolean: Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution - `status` 'ACTIVE' | 'INACTIVE', nullable: 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. - `default_for_app_calls` boolean, nullable: 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` string, nullable: 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` string, nullable: 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. ## Response `200` The voice number as stored - 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, status is not ACTIVE or INACTIVE, callback_url is not a public HTTP or HTTPS URL, agent_id is not an agent id or null, default_for_app_calls is false, the body changes nothing, or an inactive number was made the default - `401`: Unauthorized - Invalid API credentials - `403`: Forbidden - `404`: This account has no voice number for that number, or agent_id is not one of your voice agents - `409`: The number is the default line for app calls and other active voice numbers remain - `500`: Internal server error - `502`: The number could not be moved to or from the voice agent, or agent_id was sent while numbers cannot be bound to agents; nothing was written ## Changes - **2026-10-28** `41acb2ceb84d`: 4 info - added the new optional request property `allOf[subschema #2: SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsPatchVoiceChannelRequest_Properties]/agent_id` - added the non-success response with the status `502` - 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/patch.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)