Credit usage
| Name | Type | Description |
|---|---|---|
| Auth-Token | string | Input your unique token here. This is required to submit an API request. |
| Add-Metadata (Optional) |
boolean | Specify whether the response should return all fields and values, in addition to the main core information. |
| Reference-Id (Optional) |
string | Identifier that will be returned to the response to help you track the request. |
| Timeout-Seconds (Optional) |
integer | Maximum time you are prepared to wait for a response, expressed in seconds. Acceptable values: 2-15. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned. The default value of this setting is 15. |
| Field | Type | Description | |
|---|---|---|---|
| number | string | The phone number that you are submitting for validation, either in the format local to your country or with phone country code. | |
| output_format (Optional) |
string | The desired format of the phone number:
|
|
| cache_value_days (Optional) |
integer | The number of days to look back in cache for the validation result for this phone number. If the result is cached, the response will be returned faster. Acceptable values from 0 (no cache) to 30. The default value of this setting is 7. |
|
| country_iso (Optional) |
string | You can indicate the 3-letter ISO country code if the phone number that is subject to validation doesn't contain a phone country code. The default value of this setting is empty. |
|
| get_ported_date (Optional) |
boolean | A boolean indicator to attempt to retrieve the last ported date of the phone number. This feature is available for selected countries only.
Costs |
|
| get_disposable_number (Optional) |
boolean | A boolean indicator to attempt to verify if the number is known to be disposable. A disposable number is a shared mobile (or landline) that can be used to receive a text, or phone call. The default value of this setting is false. |
|
| supplementary_live_status (Optional) |
object | Object defining the requested live statuses. This feature is available for selected countries only. Find more information about country coverage on our functionality overview. | |
| mobile | collection | A list of 3-letter ISO country codes used to request supplementary live status information for mobile phone numbers.
Costs |
|
| landline | collection | A list of 3-letter ISO country codes used to request supplementary live status information for landline phone numbers.
Costs |
|
| Field | Description |
|---|---|
| number | The phone number that you are submitting for validation, either in the format local to your country or with phone country code. |
| validated_phone_number | The validated phone number. Also includes the international country calling code. Note that this field is returned even if the phone number has a confidence of "Unverified". |
| formatted_phone_number | The phone number in the format you specified in output_format. |
| phone_type | The type of phone number:
|
| confidence | The outcome of the validation:
|
| ported_date | The date that the phone number was last ported if the number has been ported to a different network other than the originally assigned network. This value would be returned if the get_ported_date request parameter is set to true. |
| disposable_number | This field will return a Yes if the number is known to be from a disposable network, or has been found on a website advertising disposable numbers, otherwise it will return Unknown. |
| Field | Description |
|---|---|
| original_operator_name | The name of the MSISDN operator with which the phone number was initially registered. Note that operator names may change over time due to acquisitions, mergers, or regulatory updates, among other factors. |
| original_network_status | The status of the network where the phone number was originally registered. |
| original_home_network_identity | The Mobile Country Code (MCC) and Mobile Network Code (MNC) where the phone number was originally registered. |
| original_country_prefix | The international calling code of the country where the phone number was originally registered. |
| original_country_name | The name of the country where the phone number was originally registered. |
| original_country_iso | The 3-letter ISO code of the country where the phone number was originally registered. |
| operator_name | The name of the MSISDN operator with which the phone number is currently registered. Note that operator names may change over time due to acquisitions, mergers, or regulatory updates, among other factors. |
| network_status | The status of the network where the phone number is currently registered. |
| home_network_identity | The Mobile Country Code (MCC) and Mobile Network Code (MNC) where the phone number is currently registered. |
| country_prefix | The international calling code of the country where the phone number is currently registered. |
| country_name | The name of the country where the phone number is currently registered. |
| country_iso | The 3-letter ISO code of the country where the phone number is currently registered. |
| is_ported | Indicates whether the phone number is ported or not. |
| cache_value_days | The requested number of days to look back in the cache for this phone number. |
| date_cached | The last date this phone number was checked. |
| (Optional) email_to_sms_address* | Email address which can be used to send SMS messages to this phone number. |
| (Optional) email_to_mms_address* | Email address which can be used to send MMS messages to this phone number. |
/* Only supported in some countries
| Country | Network |
|---|---|
| Argentina | Claro |
| Movistar | |
| Nextel | |
| Alertas Personal | |
| Aruba | Setar |
| Australia | Optus Mobile |
| Brazi | Claro |
| Vivo | |
| Bulgaria | Mobitel |
| Canada | Aliant Mobility |
| Bell | |
| Fido | |
| Telus Mobility | |
| Lynx Mobility | |
| MTAS Mobility | |
| Rogers Wireless | |
| Sasktel | |
| Virgin Mobile Canada | |
| China | China mobile |
| Colombia | Claro (formerly Comcel) |
| Movistar | |
| Dominica | Digicel |
| Egypt | Vodafone |
| France | SFR (** limited coverage) |
| Bouygues Telecom (** limited coverage) | |
| Guyana | Cellink |
| Hong Kong | CSL Hong Kong |
| Iceland | Vodafone |
| Siminn | |
| India | Aircel |
| Airtel elap | |
| Airtel Chennai | |
| Airtel Karnataka | |
| Airtel Kerala | |
| Airtel Kolkata | |
| Airtel Tamil Nadu | |
| Idea Cellular | |
| Loop Mobile | |
| Ireland | Meteor |
| Vodafone | |
| Japan | KDDI |
| NTT Doomo | |
| Softbank | |
| Y Mobile | |
| Mauritius | Emtel |
| Nepal | NCell (Axiata) |
| New Zealand | Telecom New Zealand |
| Vodafone | |
| Panama | Cable Wireless |
| Poland | Orange |
| Plus | |
| Puerto Rico | Claro |
| Russia | Beeline |
| Singapore | M1 |
| Spain | Movistar |
| Vodafone | |
| South Africa | MTN |
| Vodacom | |
| Sri Lanka | Mobitel |
| Sweden | Tele2 |
| Switzerland | Sunrise |
| Korea | SK Telecom |
| Ukraine | Beeline |
| USA | Alltel |
| Alaska Communications | |
| AT&T | |
| Boost Mobile | |
| Bluegrass Cellular | |
| Carolina West Wireless | |
| Cellcom new cell Inc | |
| Cellcom Nsighttel Wireless | |
| Cellcom NSight Spectrum | |
| C Spire Wireless | |
| Chariton Valley Communications | |
| Cincinnati Bell | |
| Chat Mobility | |
| DTC Wireless | |
| GCI Wireless | |
| IOWA Wireless Services | |
| Metro PCS | |
| Nextel | |
| Pioneer Cellular | |
| Sprint | |
| Southern Communications | |
| Syringa Wireless | |
| T Mobile | |
| US Cellular | |
| Verizon | |
| Viaero | |
| Virgin Mobile | |
| West Central | |
| Uruguay | Movistar |
Below you have an example of a successful response returned by the API.
Content-Type: application/json; charset=utf-8
Date: 30 May 2019 09:53:17 GMT
Message: OK
Reference-Id: My id Abc 321
Transaction-Id: f4d0c1d2-d529-49b0-82d6-268d57c89c64
X-Rate-Limit-Limit: 9000
X-Rate-Limit-Remaining: 8999
X-Rate-Limit-Reset: 1559210040
{
"result": {
"number": "01234567891",
"validated_phone_number": "01234567891",
"formatted_phone_number": "(123) 456-7891",
"phone_type": "Mobile",
"confidence": "Verified"
},
"metadata": {
"phone_detail": {
"original_operator_name": "T-Mobile",
"original_network_status": "Available",
"original_home_network_identity": "310200",
"original_country_prefix": "1",
"original_country_name": "United States of America",
"original_country_iso": "USA",
"operator_name": "Verizon",
"network_status": "Available",
"home_network_identity": "311480",
"country_prefix": "1",
"country_name": "United States of America",
"country_iso": "USA",
"is_ported": "Yes",
"cache_value_days": 0,
"date_cached": "2020-04-22",
"email_to_sms_address": "7087694383@vtext.com",
"email_to_mms_address": "7087694383@vzwpix.com"
}
}
}