TelephonyPhone Numbers

Import Phone Number

Import a phone number into the workspace. The `source` 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_…’.

Request

This endpoint expects an object.
e164stringRequired

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

sourceenumRequired

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

Optional human-readable label.

trunk_idstringOptional

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

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 source=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.

Response

The imported 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
402
Payment Required Error