GEThttps://core-api.heysadie.ai/phone-numbers/available
country locality areaCode success data phoneNumbers phoneNumber region postalCode isoCountry total metadata timestamp version path error code message details fieldList available numbers
Returns a list of phone numbers available for purchase. These numbers come directly from our external phone number provider and are not yet assigned to your account. You can filter the results by: - `country` (required): Country code such as US, AU, NZ, CA, GB, CH. Note: IT (Italy) may not be available for searches yet. - `locality` (optional): City or region name like Melbourne, Sydney, Perth, etc. - `areaCode` (optional): Area code that the phone number should start with (e.g., '438' for numbers starting with +1 438..). Use this endpoint when you want to show your users a list of numbers they can choose to register for their assistant. ⚠️ This does not return numbers you already own — use `GET /phone-numbers` for that.
Try it in the API ExplorerExample request
curl "https://core-api.heysadie.ai/phone-numbers/available?country=string" \
-H "Authorization: ApiKey YOUR_API_KEY"Authentication
Authenticate with an API key in the Authorization header using the ApiKey scheme — see Authentication for how keys work and where to get them.
AuthorizationstringrequiredAPI key in the ApiKey scheme: ApiKey YOUR_API_KEY. Tenant keys authorize their own tenant; organization keys can act on any tenant in the organization.
X-Tenant-Idstring (uuid)optionalRequired when authenticating with an organization key — selects the tenant the request acts on. Omit with tenant keys.
Request
Query parameters
countrystringrequiredCountry code (e.g., US, AU, NZ, CA, GB, CH). Note: IT may not be available yet.
localitystringoptionalOptional locality name (e.g., Melbourne, Perth)
areaCodestringoptionalOptional area code that the phone number should start with (e.g., '438' for numbers starting with +1 438..)
Responses
successbooleanrequireddataobjectoptionalShow 2 child properties
phoneNumbersobject[]requiredAvailable phone numbers for purchase
Show 5 item properties
phoneNumberstring | nullrequiredlocalitystring | nullrequiredregionstring | nullrequiredpostalCodestring | nullrequiredisoCountrystring | nullrequiredtotalnumberrequiredTotal number of available phone numbers returned
metadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional400
successbooleanrequirederrorobjectoptionalShow 3 child properties
codeenumrequired"VALIDATION_ERROR"messagestringrequireddetailsobject[]optionalShow 2 item properties
fieldstringrequiredmessagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional401
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"UNAUTHORIZED"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional403
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"FORBIDDEN"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional404
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"RESOURCE_NOT_FOUND"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional500
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"INTERNAL_SERVER_ERROR"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional