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
| 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 to the REST API Error Codes page.