TelephonyPhone Numbers

Purchase Phone Number

Purchase a phone number on Speechify's master Twilio account. The number is billed to Speechify until released; each workspace is capped at a small number of purchased numbers (see 422 response) independent of the overall 100-number cap. `e164` must come from a recent `SearchAvailablePhoneNumbers` response — carriers reject buys against numbers that are no longer in inventory. The returned phone number is wired for both inbound (when `agent_id` is set, or after a later `PATCH`) and outbound calls (via the workspace's shared outbound trunk).

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
e164stringRequired
The E.164 number to buy. Must currently be in carrier inventory.
labelstringOptional

Optional human-readable label.

agent_idstringOptional

Optional agent to bind the number to at purchase time. Prefixed wire identifier (agent_<26 char Crockford base32>).

Response

The purchased 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
422
Unprocessable Entity Error
503
Service Unavailable Error