API ReferenceTelephonyPhone numbers

Import Phone Number

Beta
Import a phone number into the workspace. The `provider` field determines the provisioning path: - `livekit` - LiveKit purchases the number on your behalf. US inbound only. Quickest path for local testing. - `twilio` - Provide your Twilio Account SID, Auth Token, and the E.164 number you already own. We provision an Elastic SIP Trunk on your Twilio account automatically. - `byoc` - Provide an existing SIP trunk ID. The number is registered against that trunk. Returns 402 when the workspace has reached the 100-number cap.

Authentication

AuthorizationBearer

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

Headers

Speechify-VersionstringOptional

Request

This endpoint expects an object.
e164stringRequired

The phone number in E.164 format. For provider=livekit this is the number you want LiveKit to purchase. For provider=twilio, provider=telnyx, and provider=byoc it is the number you already own.

providerenumRequired

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.
labelstringOptional

Optional human-readable label.

trunk_idstringOptional

For provider=byoc: the SIP trunk to bind this number to. Prefixed wire identifier (trunk_<26 char Crockford base32>). Not required for provider=livekit, provider=twilio, or provider=telnyx.

agent_idstringOptional

Optional agent to bind on import. Prefixed wire identifier (agent_<26 char Crockford base32>).

twilioobjectOptional

Twilio credentials for the one-click import flow. Used only when provider=twilio. The Account SID and Auth Token are used to provision an Elastic SIP Trunk on the customer’s Twilio account pointing at LiveKit’s SIP endpoint, then stored for future trunk management operations.

telnyxobjectOptional

Telnyx connection details for the bring-your-own-connection import flow. Used only when provider=telnyx. You provision an FQDN connection on your Telnyx account whose inbound calls forward to Speechify’s LiveKit SIP ingress, assign the number to it, then import by passing the connection’s id. A second number on the same connection reuses the one shared trunk + dispatch rule.

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 imported 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
422
Unprocessable Entity Error