NumVerify offers a full-featured yet simple RESTful JSON API for national and international phone number validation and information lookup for a total of 232 countries around the world.
Requested numbers are processed in real-time, cross-checked with the latest international numbering plan databases and returned in handy JSON format enriched with useful carrier, geographical location and line type data.
Integrating the numverify API into your application will enable you to verify the validity of phone numbers at the point of entry, protecting you from fraud and increasing good leads.
After signing up, every user is assigned a personal API Access Key - a unique "password" used to make requests to the API.
To authenticate with the numverify API, simply attach your access_key to the base endpoint URL:
http://apilayer.net/api/validate?access_key=YOUR_ACCESS_KEY
Since all existing validation data is returned by the same main API endpoint, making a phone number verification request to the numverify API is simple.
Most basic API request:
Take a look at the following API request URL: (If you would like to try it yourself, get a Free Plan and don't forget to attach your Access Key to the URL)
http://apilayer.net/api/validate ? access_key = YOUR_ACCESS_KEY & number = 14158586273
As you can see, in addition to the access_key parameter, there is only one required parameter (number) to start validating phone numbers.
Optional parameters:
country_code specify a country code if you intend to use a national phone number for your request format set to "1" in order to request prettified JSON result set (use only for debugging!) callback append your preferred JSONP callback function name. (See "JSONP Callbacks" section)
All numverify validation data is returned in universal and lightweight JSON format. Find below a standard API result set:
{
"valid": true,
"number": "14158586273",
"local_format": "4158586273",
"international_format": "+14158586273",
"country_prefix": "+1",
"country_code": "US",
"country_name": "United States of America",
"location": "Novato",
"carrier": "AT&T Mobility LLC",
"line_type": "mobile"
}
API response objects:
Each API response consists of 9 individual JSON response objects:
Object | Description |
---|---|
"valid" | Returns true if the specified phone number is valid. |
"number" | Returns the phone number you specified in a clean format. (stripped of any special characters) |
"local_format" | Returns the local (national) format of the specified phone number. |
"international_format" | Returns the international format of the specified phone number. |
"country_prefix" | Returns the international country dial prefix for the specified phone number. |
"country_code" | Returns the 2-letter country code assigned to the specified phone number. |
"country_name" | Returns the full country name assigned to the specified phone number. |
"location" | If available, returns the location (city, state, or county) assigned to the specified phone number. |
"carrier" | Returns the name of the carrier which the specified phone number is registered with. |
"line_type" | Returns the line type of the specified phone number (See: Line Type Detection) |
Paid Customers may establish a secure connection (industry-standard SSL) to the numverify API and all data provided by and accessible through it.
To connect securely, simply attach an s to the HTTP Protocol. (resulting in https://)
If your query fails, the numverify API will return a 3-digit error-code, an internal error type and a plain text "info" object containing suggestions for the user.
Find below an example error - triggered when no phone number was specified:
{
"success": false,
"error": {
"code": 210,
"type": "no_phone_number_provided",
"info": "Please specify a phone number. [Example: 14158586273]"
}
}
Type | Message | Description |
---|---|---|
404 | "404_not_found" | User requested a resource which does not exist. |
101 | "missing_access_key" | User did not supply an Access Key. |
101 | "invalid_access_key" | User entered an invalid Access Key. |
103 | "invalid_api_function" | User requested a non-existent API function. |
210 | "no_phone_number_provided" | User did not provide a phone number. |
211 | "non_numeric_phone_number_provided" | User did not provide a numeric phone number. |
310 | "invalid_country_code" | User provided an invalid 2-letter country code. |
104 | "usage_limit_reached" | User has reached or exceeded his Subscription Plan's monthly API Request Allowance. |
105 | "https_access_restricted" | The user's current Subscription Plan does not support HTTPS Encryption. |
102 | "inactive_user" | The user's account is not active. User will be prompted to get in touch with Customer Support. |
The numverify API also supports JSONP Callbacks. To use this feature, simply attach:
callback = CALLBACK_FUNCTION
to any API Endpoint, and the result set will be returned wrapped in the callback function you specified.
Example query:
http://apilayer.net/api/validate?callback=CALLBACK_FUNCTION
Not sure about what JSONP does? Here's a helpful Stack Overflow thread.
Example response:
CALLBACK_FUNCTION ({
{
"valid": true,
"number": "14158586273",
"local_format": "4158586273",
"international_format": "+14158586273",
"country_prefix": "+1",
"country_code": "US",
"country_name": "United States of America",
"location": "Novato",
"carrier": "AT&T Mobility LLC",
"line_type": "mobile"
}
})
Note: The API also supports Access-Control (CORS) headers.
In order to enhance readability the numverify API features a built-in JSON format function, which displays the API's Response in typically JSON-structured format.
To enable this function, simply attach format=1 to any valid API request URL:
http://apilayer.net/api/validate ? access_key = YOUR_ACCESS_KEY [...] & format = 1
Please be aware that enabling format increases the API response's file size and might cause parsing problems. It should be used for debugging purposes only.
Making a phone number validation request to the numverify API is simple. Simply append the number parameter followed by the phone number you would like to validate to the API's validate endpoint.
Example query:
Take a look at the following API request URL: (If you would like to try it yourself, get a Free Plan and don't forget to attach your Access Key to the URL)
http://apilayer.net/api/validate ? access_key = YOUR_ACCESS_KEY & number = 14158586273
Number input formats and correction mechanisms:
While it is most efficient to provide phone numbers in a strictly numeric format (e.g. 441179287870), the numverify API is also capable of processing numbers containing special characters (e.g. +44 (0) 117 928 7870).
Every valid phone number request comes with three geographical identifiers, a 2-digit country_code, the corresponding full country_name, and an individual location object containing the city, state or county where the requested phone number is registered.
[...] "country_code": "US", "country_name": "United States of America", "location": "Novato", [...]
Please note: While the two JSON objects indicating the country will be returned in nearly 100% of the cases, the location object may not be available for certain numbers.
If you intend to specify a phone number in its national (local) format, you will be required to provide additional country information, simply by appending your preferred 2-digit country code to the API's country_code parameter and including it in your API request URL.
http://apilayer.net/api/validate ? access_key = YOUR_ACCESS_KEY & number = 4158586273 & country_code = US
Important: When working with national phone numbers, specifying a country code is obligatory.
Important: Please do not specify an additional country_code parameter when working with international numbers (e.g. 14158586273).
While phone numbers help businesses identify and legitimize customers, some numbers are very easy to retrieve from certain carriers. For exmaple, anyone can quickly register multiple phone numbers from a free online provider, making it easy to create fake profiles.
To address this risk, the numverify API will return a separate carrier object containing the name of the carrier the requested phone number is registered with. This way businesses can require additional identity authentication for carriers associated with higher fraud instances.
[...] "carrier": "AT&T Mobility LLC", [...]
Please note: Carrier information may not be available for certain phone numbers.
Certain number types don’t accept all communications, e.g. many VoIP and landline numbers do not accept SMS messages. This is why the numverify API will detect a number's line type and return a line_type JSON object containing the necessary information for you to identify which kind of communications a number can accept.
[...] "line_type": "mobile"
Knowing the line type of a given phone number makes it easy to decide optimally whether to send voice or text communications and ensures full compliance with the FCC Telephone Consumer Protection Act (TCPA).
Line types:
Finde below a list of all line types supported by the API.
Line Type | line_type Object |
---|---|
Mobile Phone | mobile |
Landline | landline |
Special Services (e.g. Police) | special_services |
Toll-Free Numbers (e.g. hotels) | toll_free |
Premium Rate Numbers (e.g. paid hotlines) | premium_rate |
Satellite | satellite |
Paging | paging |
The numverify API supports phone number validation for a total of 232 countries (territories) around the world. Using the API's countries endpoint, you may access a comprehensive list of supported areas, including country names and dialling codes.
{ "AF": { "country_name": "Afghanistan", "dialling_code": "+93" }, "AL": { "country_name": "Albania", "dialling_code": "+355" }, "DZ": { "country_name": "Algeria", "dialling_code": "+213" }, "AS": { "country_name": "American Samoa", "dialling_code": "+1" }, [...]
In order to access this JSON file, simply append your personal API access key to the countries endpoint.
http://apilayer.net/api/countries?access_key=YOUR_ACCESS_KEY
Find below a simple way of using PHP (cURL) to verify a phone number:
// set API Access Key $access_key = 'YOUR_ACCESS_KEY'; // set phone number $phone_number = '14158586273'; // Initialize CURL: $ch = curl_init('http://apilayer.net/api/validate?access_key='.$access_key.'&number='.$phone_number.''); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Store the data: $json = curl_exec($ch); curl_close($ch); // Decode JSON response: $validationResult = json_decode($json, true); // Access and use your preferred validation result objects $validationResult['valid']; $validationResult['country_code']; $validationResult['carrier'];
Find below a simple way of using jQuery.ajax to verify a phone number:
// set endpoint and your access key var access_key = 'YOUR_ACCESS_KEY'; var phone_number = '14158586273'; // verify phone number via AJAX call $.ajax({ url: 'http://apilayer.net/api/validate?access_key=' + access_key + '&number=' + phone_number, dataType: 'jsonp', success: function(json) { // Access and use your preferred validation result objects console.log(json.valid); console.log(json.country_code); console.log(json.carrier); } });
Please note: In this example, the use of JSONP is entirely optional.