Request, response and examples

Headers

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.

Body parameter

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 string The desired format of the phone number: E164, PLUS_E164, NATIONAL, any 3-letter ISO country code. If not specified, the default format, E164, will be used.
cache_value_days 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. If not specified, the default value, 7, will be used.
country_iso 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.
get_ported_date boolean A boolean indicator to attempt to retrieve the last ported date of the phone number. Please note that this feature is available for selected countries and there would be additional charge if a date is successfully retrieved.
get_disposable_number 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.
supplementary_live_status string
  • Mobile - An indicator to attempt to get supplementary live status for Mobile Phone Number.
  • Landline - An indicator to attempt to get supplementary live status for Landline Phone Number.
  • Availability can be found here

Body fields

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 status of "Unverified"
formatted_phone_number The phone number in the format you specified in "output_format".
phone_type The type of phone number:
  • Mobile- A phone number assigned to a Mobile Telephone Operator / Cell Phone Operator
  • Landline- A wired telephone in a fixed location such as home or office.
  • Mobile or landline- The telephone number could belong to either a mobile or landline type phone.
  • Toll free- The number can be called from within the home country at no cost. There may be a charge to call this number from outside the home country. This is also called Freephone.
  • Premium- There is a premium charge added to call this number, often there is a service provided on the number so the callee typically receives revenue from the call.
  • Shared cost- This telephone number will charge both the caller and callee at the same time. There will be an additional charge to call this type of number.
  • VoIP- Assigned to a VoIP provider who delivers calls and text messages over the internet.
  • Stage and screen- Reserved by a regulatory body specifically for use as fictitious numbers in films, stage and screen. No real end user will be assigned.
  • Pager- Allocated to a device that receives and displays numeric or alphanumeric messages.
  • Universal access number- Typically used by companies to route calls to multiple destinations depending on parameters such as time of day, where the caller currently resides (so not linked to any specific locality within the country), capacity and more.
  • Personal number- Intended to be used by individuals which may route to multiple locations (home, office and cell). Some are charged at a Premium number rate.
  • Voicemail only- Access number for voicemail only.
  • Bad format- The number you submitted could not be identified as a valid telephone number. Check that you added an international country code.
  • Unknown- Valid number format but not verified with network lookup. Could try again at a later date.
confidence The outcome of the validation:
  • Verified- Number format validated and number verified.
  • Absent- Number format validated and number verified via network lookup but not currently available (e.g. phone off, out of range).
  • Teleservice not provisioned- Number is assigned to a SIM card which is not allowed to make or receive telephone calls. Typically a ‚Äúdata only SIM".
  • Unverified- Invalid number format supplied.
  • Unknown- Valid number format but not verified with network lookup.
  • No coverage- Unable to detect the live status for the telephone network.
  • DeadNumber- has been confirmed to be dead by the network and will not receive calls or text messages.
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 boolean 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 an Unknown.

Metadata fields

Field Description
original_operator_name The name of the MSISDN operator where the phone number was originally registered.
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 where the phone number is currently registered.
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

Supported 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"
    }
  }
}