---
title: "Set or clear one number's agent voice"
method: PATCH
path: "/voice/bridge/numbers"
tags: ["voice"]
---

# Set or clear one number's agent voice

`PATCH /voice/bridge/numbers`

## Request

- Base URL: `https://corebee.ai/api/v1`
- URL: `https://corebee.ai/api/v1/voice/bridge/numbers`
- Auth: HTTP bearer

Choose the Cartesia voice the conversational agent speaks in for calls placed from one of your DIDs. Send a canonical UUID to set it, or null to clear it and return the number to the platform default voice. voice_id is REQUIRED in the body: omitting the key is a 400, not a clear, so a mistyped field name can never silently reset a number. The id is validated for SHAPE only, we do not keep a list of valid Cartesia voice ids, so any well-formed UUID is accepted and it is yours to confirm that it names a voice on your account. A malformed id is a 400 that names the accepted form; it is never a silent no-op. from_number must be a Telnyx DID owned by your organization, else 403. Any field other than from_number and voice_id is a 400 that names the right route: the agent SPOKEN LINES live at PATCH /voice/bridge/numbers/instructions, and sending "instructions" here used to be silently discarded. Requires the voice:bridge scope.

## Request body

- BridgeNumberVoiceUpdate
  - `from_number` string, required: E.164 DID owned by your organization. 403 if it is not.
  - `voice_id` string, nullable, required: Canonical Cartesia voice UUID, or null to clear the choice and use the platform default voice. REQUIRED: omitting the key is a 400, never a clear. Validated for shape only, any well-formed UUID is accepted, so confirm it names a voice on your Cartesia account.

## Response `200`

Updated

- object
  - `data` BridgeNumberVoiceResult, required
    - `from_number` string
    - `voice_id` string, nullable
    - `using_platform_default` boolean: True when voice_id is null, i.e. this number speaks in the platform default voice.

## Other responses

- `400`: Validation error
- `401`: Invalid or missing credential
- `403`: Forbidden (missing scope, or resource not owned by the credential org)
- `404`: Not found
- `409`: Conflict (code conflict): the column backing this feature has not been added to the database yet. The message names the migration. Nothing was written and every number reads as unset.
- `500`: Error

---

[API](https://skmtc.dev/corebee/apis/corebee-api.md) · [All operations](https://skmtc.dev/corebee/apis/corebee-api/llms.txt) · [OpenAPI document](https://skmtc.dev/corebee/apis/corebee-api/revisions/a48ea543b4dc?raw)