Search available phone numbers to buy
Searches carrier inventory for numbers you can buy — this reads live availability, not the numbers you already own.
Searches carrier inventory for numbers you can buy — this reads live availability, not the numbers you already own. Narrow the search with country (ISO 3166-1 alpha-2, defaults to US; a value that is not two letters is a 400), areaCode, contains (digits the number must include), and type; limit accepts 1–100 and defaults to 10. Each result includes phoneNumber, numberType, locality, region, capabilities, monthlyCostUsd, setupCostUsd, and purchasable. Numbers your account cannot yet buy — for example because they require identity verification — come back with purchasable: false and a masked phoneNumber. Requires the phone:read scope.
Scope: phone:read. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
country | string | no | ISO 3166-1 alpha-2 country code. Defaults to US. (min length 2, max length 2) |
areaCode | string | no | National destination code (e.g. 415). |
contains | string | no | Digits the number must contain. |
type | "local", "toll_free", "national", "mobile" | no | Number type. |
limit | integer | no | Maximum results (1-100). Defaults to 10. (minimum 1, maximum 100) |
Response
200 Success. Body: application/json, AvailablePhoneNumberListResponse.
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" | yes | |
data | array of AvailablePhoneNumber | yes |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |
Provision a phone number
Provisions the exact number a prior available search returned, passed as phoneNumber in E.164, and starts recurring monthly billing for it.
Retrieve a phone number
Retrieves one owned phone number by id, in the same shape as a row from the list endpoint: status, capabilities, monthlyCostUsd, setupCostUsd, requirements, metadata, its inboxId/agentId bindings, and its inbound agent (inboundInstructions, inboundGreeting, inboundVoice, inboundLanguage; null means the default).