TelephonyPhone Numbers

Update Phone Number

Update a phone number. Only label and agent_id are mutable; source and e164 are immutable after import. Pass null for agent_id to unbind the number from its current agent.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

idstringRequired

Request

This endpoint expects an object.
labelstringOptional
New label. Pass an empty string to clear.
agent_idstringOptional

Agent to bind the number to. Prefixed wire identifier (agent_<26 char Crockford base32>).

clear_agent_idbooleanOptional

When true, unbinds the current agent (clears agent_id). Wins over agent_id when both are sent.

Response

The updated phone number.
idstring

Prefixed wire identifier (phone_<26 char Crockford base32>). ADR 0015 Cluster 3 hard-break: URL paths accept only this prefixed form; legacy UUID path parameters are rejected with 404 as of Cluster 3.

e164string

The phone number in E.164 format (e.g. +12025551234).

sourceenum

Where the number came from. Determines the provisioning and portability path.

  • livekit - LiveKit owns the carrier relationship; US inbound only.
  • twilio - Customer’s own Twilio number bridged via Elastic SIP Trunk.
  • byoc - Any SIP provider using a customer-supplied trunk.
  • twilio_purchased - Bought through POST /v1/agents/phone-numbers/purchase on Speechify’s master Twilio account; billed to Speechify.
  • verified_caller_id - Customer-verified outbound caller ID on their own Twilio account (Twilio’s OutgoingCallerIds resource). Server-determined at import time: when an e164 submitted with source=twilio is not a full DID on the customer’s account but IS a verified caller ID, the resulting row gets this source. Outbound-only, never agent-bindable, rides the customer’s existing shared Twilio trunk for outbound routing. Requires a prior twilio full-DID import from the same account; without it the import returns 400.
capabilitieslist of enums
What this number can do.
created_atdatetime
When the number was imported.
updated_atdatetime
When the number was last modified.
labelstring

Optional human-readable label set by the customer.

trunk_idstring
ID of the SIP trunk backing this number, if applicable.
agent_idstring
ID of the agent that answers calls to this number. Null when unbound.
livekit_phone_number_idstring

LiveKit’s own phone number ID (populated for source=livekit only).

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error