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.

Business Continuity - API Overages

Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.

What is an overage?

An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.

Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.

Why does APILayer have overage fees?

Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.

How do I know if I will be charged for overages?

When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.

How will I be charged for my API subscription?

You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.

What happens if I don’t have any overage fees?

In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.

What if I consistently have more API calls than my plan allows?

If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.

I would like to upgrade my plan. How can I do that?

You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.