API ReferenceTelephonyPhone numbers

Search Available Phone Numbers

Beta

Search carrier inventory for phone numbers available to purchase. Currently restricted to the US (country=US); pass area_code to narrow to a specific NPA. The returned numbers are not held; a subsequent POST /v1/agents/phone-numbers/purchase against the same E.164 may fail with 4xx if the number has been taken in the meantime.

Authentication

AuthorizationBearer

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

Headers

Speechify-VersionstringOptional

Query parameters

countrystringOptionalDefaults to US

ISO-3166 alpha-2 country code. Defaults to “US”; only “US” is supported in v1.

area_codestringOptional

Three-digit NPA to filter inventory to a region.

limitintegerOptionalDefaults to 20
Max results to return. Capped at 50.

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

Available numbers (may be empty if no inventory matches).

numberslist of objects

Available numbers (may be empty if no inventory matches).

Errors

400
Bad Request Error
401
Unauthorized Error
503
Service Unavailable Error