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

Optional workspace project to place this resource in (prefixed proj_... id). Omit for the implicit Default project. An unknown id returns 404 project_not_found.

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

Speechify-Request-IdstringOptional
Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-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. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

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

Optional human-readable label set by the customer.

trunk_idstringOptional
ID of the SIP trunk backing this number, if applicable.
agent_idstringOptionalformat: "^agent_[0-9a-hjkmnp-tv-z]{26}$"

ID of the agent this number’s calls run as. Null only while the number is unbound. Pointing a number at a brain provisions an agent too - it is what gives an externally-brained call a conversation, transcript and lifecycle - so this is also the agent_id to pass to POST /v1/agents/outbound-calls to dial out from such a number.

brain_idstringOptionalformat: "^brain_[0-9a-hjkmnp-tv-z]{26}$"

The external brain answering this number’s traffic. Absent when the number is unbound or answered by a hosted agent. Read the endpoint, health and settings at /v1/agents/brains/{brain_id}.

iso_countrystringOptional

ISO-3166 alpha-2 country of the number. Present on purchased numbers; may be absent on imported numbers.

project_idstring or nullOptionalformat: "^proj_[0-9a-hjkmnp-tv-z]{26}$"

Workspace project this resource lives in (prefixed external id). Null means the implicit Default project.

reputationobjectOptional

Carrier spam-reputation status for the number, refreshed on a schedule. Present once the number has been checked at least once; omitted otherwise.

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error