Purchase Phone Number | SpeechifyAI API

Purchase a phone number on Speechify’s master Twilio account. The number is billed to Speechify until released. A plan that includes no purchased numbers (e.g. Free) returns 402; a plan that has used its full included quota returns 422. This is 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 binding the number to an agent via POST /v1/agents/{agent_id}/phone-numbers/{phone_number_id}) and outbound calls (via the workspace’s shared outbound trunk).

Purchase a phone number on Speechify's master Twilio account. The number is billed to Speechify until released. A plan that includes no purchased numbers (e.g. Free) returns 402; a plan that has used its full included quota returns 422. This is 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 binding the number to an agent via `POST /v1/agents/{agent_id}/phone-numbers/{phone_number_id}`) and outbound calls (via the workspace's shared outbound trunk).

Authentication

AuthorizationBearer

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

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.

e164stringRequired

The E.164 number to buy. Must currently be in carrier inventory.

labelstringOptional

Optional human-readable label.

providerenumOptional

Which carrier’s Speechify-managed account to buy on. Optional; defaults to twilio_purchased.

agent_idstringOptional

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

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.

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 purchased 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

402

Payment Required Error

409

Conflict Error

422

Unprocessable Entity Error

503

Service Unavailable Error

$	curl -X POST https://api.speechify.ai/v1/agents/phone-numbers/purchase \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"e164": "+14155552671",
>	"label": "Sales line",
>	"agent_id": "agent_01HS..."
>	}'

1	{
2	"id": "phone_01k7m6etzwf057j6w0zmdsgppr",
3	"e164": "+12025551234",
4	"type": "twilio",
5	"capabilities": [
6	"inbound",
7	"outbound"
8	],
9	"created_at": "2026-04-17T10:00:00Z",
10	"updated_at": "2026-04-17T10:00:00Z",
11	"label": "Support line",
12	"trunk_id": "trunk_01k4n5jjx9k1qqxv5sz7vzsgty",
13	"agent_id": "agent_01k1e836vy9ye7xygskysvcjh0"
14	}