REST API –

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 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

Parameter Type Description
Capabilities string Comma delimited list of capabilities.
May be:
Voice : Audio calls.
SMS : Text messages.
MMS : Multimedia messages.
CountryCode
(ISO 3166-1 Format)
string Only available numbers that match the specified country code will be returned. E.g AU or US.
Type string Restrict 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).
IncludeBeta boolean Optionally 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_Count integer Specify the number of results to return. Default number of results is 200.
Results_Skip integer Specify 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.

Parameter Type Description
SimilarTo
(E.164 Format)
string Filters 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.

Parameter Type Description
Prefix string Filters 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.

Parameter Type Description
Region string Filters to numbers that are based within this region (or state/province).
City string Filters to numbers that are based within this city (or suburb).
Postcode string Filters 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
Parameter Type Description
Number
(E.164 Format)
string The phone number.
CountryCode
(ISO 3166-1 Format)
string The country code associated with the number.
Region string The geographical region associated with the number.
City string The city associated with the number if applicable.
Type string Restrict 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).
Capabilities string Comma delimited list of capabilities. May be:
Voice : Audio calls.
SMS : Text messages.
MMS : Multimedia messages.
AddressRequirement string Address requirement for number registration. May be: None, Any, Local, Foreign or City

400 – Error

For error codes and messages, please refer here.