Search Available Numbers
Search for available phone numbers in a specific country.
Your role needs the phone_number:view permission. Otherwise the request fails with 403 {"error": "Insufficient permissions"}.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Query Parameters
countrystringrequiredCountry code to search for numbers: US, CA, AU, or GB when it appears in Available Countries. Any other country also needs an addressSid query parameter.
typestringrequiredlocal or mobile. Not required for AU. For GB, only mobile is available (local returns 400 with code UK_LOCAL_NOT_AVAILABLE).
Toll-free numbers are not sold through the API. tollFree returns 403 with code TOLL_FREE_NOT_AVAILABLE, and toll-free numbers are removed from every result.
containsstringSearch for numbers containing specific digits or patterns.
areaCodestringOnly numbers with this area code. Toll-free area codes (800, 833, 844, 855, 866, 877, 888) return 403 with code TOLL_FREE_NOT_AVAILABLE.
inStatestringOnly numbers in this state or region (for GB, a city).
limitnumberMaximum number of results to return. Defaults to 20 for US and CA.
Response Fields
numbersarrayArray of available phone numbers.
phoneNumberstringThe phone number in E.164 format.
friendlyNamestringA human-readable formatted version of the number.
localitystringCity or locality associated with the number.
regionstringState or region associated with the number.
capabilitiesobjectvoice, SMS, MMS and fax, each true or false.
isoCountrystringCountry code of the number.
filtersobjectAvailable filter options for the country.
supportedarrayList of supported filter types for the selected country: contains, limit, areaCode and inState for US, CA, AU and GB.
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "Country and workspace ID are required."} | country or x-workspace-id missing |
400 | {"error": "Type is required for non-AU countries."} | type missing |
400 | {"error": "...", "code": "INVALID_COUNTRY"} | GB isn't available on this deployment |
400 | {"error": "...", "code": "UK_LOCAL_NOT_AVAILABLE"} | GB with type local |
400 | {"error": "AddressSid is required for this country."} | Another country without addressSid |
403 | {"error": "...", "code": "TOLL_FREE_NOT_AVAILABLE"} | Toll-free type or area code |
500 | {"error": "Failed to fetch available phone numbers."} | The provider search failed |
{
"numbers": [
{
"phoneNumber": "+14155551234",
"friendlyName": "(415) 555-1234",
"locality": "San Francisco",
"region": "CA"
},
{
"phoneNumber": "+14155555678",
"friendlyName": "(415) 555-5678",
"locality": "San Francisco",
"region": "CA"
}
],
"filters": {
"supported": ["contains", "limit", "areaCode", "inState"]
}
}Last updated on