API ReferenceTelephonyPhone numbers

Update Phone Number

Beta

Update a phone number’s own attributes (today: label). source and e164 are immutable after import. To bind or unbind an agent, use the relationship endpoints POST/DELETE /v1/agents/{agent_id}/phone-numbers/{phone_number_id}.

Authentication

AuthorizationBearer

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

Path parameters

phone_number_idstringRequired

Phone number id (prefixed external id, phone_...).

Headers

Speechify-VersionstringOptional

Request

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

Response headers

X-Request-IDstring
Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The updated phone number.
idstringformat: "^phone_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (phone_<26 char Crockford base32>). URL paths accept only this prefixed form; legacy UUID path parameters are rejected with 404.

e164string

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

typeenum

Which provider 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.
  • telnyx - Customer’s own Telnyx number bridged via a Telnyx FQDN connection.
  • 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.
  • telnyx_purchased - Bought through POST /v1/agents/phone-numbers/purchase (with provider=telnyx) on Speechify’s master Telnyx 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 provider=twilio is not a full DID on the customer’s account but IS a verified caller ID, the resulting row gets this provider. 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_idstringformat: "^agent_[0-9a-hjkmnp-tv-z]{26}$"
ID of the agent that answers calls to this number. Null when unbound.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error