Find Available Numbers

About

Search for available numbers with particular configurations. A number of optional parameters are available in order to help tailor your query to your requirements. Available phone numbers can be purchased using our Purchase Available API.

Resource URI

Once authenticated, the following URI is used for all available number requests.

GET
/v2/Numbers

This request will return a list of available numbers matching the search query.

Request

All parameters to this method are optional unless specified otherwise. A valid request must contain at least one of the following parameters: CountryCode, Prefix or SimilarTo.

General Parameters

ParameterTypeDescription
CapabilitiesstringComma delimited list of capabilities.
May be:
Voice : Audio calls.
SMS : Text messages.
MMS : Multimedia messages.
CountryCode
(ISO 3166-1 Format)
stringOnly available numbers that match the specified country code will be returned. E.g AU or US.
TypestringRestrict search to specified phone number types delimited by commas
May be:
Local : The number prescribed to a geographical location.
Toll-Free : Upon arrival billing number. 1800 ect.
Shared-Rate : Partial recipient billing number.
National : The number is associated nationally for a purpose (E.g. VoIP).
IncludeBetabooleanOptionally include Beta numbers that are relatively new in our platform. This may include Countries where we are testing the quality testing numbers. May be: True or False
Results_CountintegerSpecify the number of results to return. Default number of results is 200.
Results_SkipintegerSpecify a number of records to skip before starting results. This enables custom pagination.

Search for Similar Numbers

This request allows you to find numbers that best match the configuration of a number you specify. Additionally, results are sorted in order of numerical similarity to the provided number.

ParameterTypeDescription
SimilarTo
(E.164 Format)
stringFilters to numbers that are of the same specification as the number supplied. Additionally, results are sorted in order of numerical prefix similarity to the provided number.

Search by Prefix

This request allows you to find numbers based on the E164 prefix.

ParameterTypeDescription
PrefixstringFilters to numbers with the specified number prefix (with or without + symbol). Must include at least two numbers E.g. +441624 or +64

Search Geographically

This request allows you to find numbers that are within the specified region, city or postcode. Using any of the below parameters also requires that the CountryCode parameter be set.

ParameterTypeDescription
RegionstringFilters to numbers that are based within this region (or state/province).
CitystringFilters to numbers that are based within this city (or suburb).
PostcodestringFilters to numbers that are local to this postcode.

Response

200 – OK

Our service will respond to every request for data with JSON formatted data. Requests for available numbers will return a list of numbers that satisfy the parameters specified in the request. Each record in the response will contain the following values.

Response Parameters
ParameterTypeDescription
Number
(E.164 Format)
stringThe phone number.
CountryCode
(ISO 3166-1 Format)
stringThe country code associated with the number.
RegionstringThe geographical region associated with the number.
CitystringThe city associated with the number if applicable.
TypestringRestrict search to specified phone number types delimited by commas
May be:
Local : The number prescribed to a geographical location.
Toll-Free : Upon arrival billing number. 1800 ect.
Shared-Rate : Partial recipient billing number.
National : The number is associated nationally for a purpose (E.g. VoIP).
CapabilitiesstringComma delimited list of capabilities. May be:
Voice : Audio calls.
SMS : Text messages.
MMS : Multimedia messages.
AddressRequirementstringAddress requirement for number registration. May be: None, Any, Local, Foreign or City

400 - Error

For error codes and messages, please refer to the REST API Error Codes page.