Specs & Overview

API Access Key & Authentication

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  
                

Make an API Request

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)
                

API Response

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:

256-bit HTTPS Encryption

Basic Pro Enterprise

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://)

API Error Codes

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

Common API errors:

JSONP Callbacks

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.

JSON Formatting

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.

API Features

Number Validation

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

Country & Location Data

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.

National (Local) 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).

Carrier Detection

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.

Line Type Detection

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.

Countries Endpoint

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  
                

Code Examples

PHP (cURL)

Validate phone number:

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'];
                

JavaScript (jQuery.ajax)

Verify phone number:

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.