API Documentation

numverify API

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.

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:


Get your free API 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)

    ? 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:

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)

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:

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.

show all errors

JSONP Callbacks

The numverify API also supports JSONP Callbacks. To use this feature, simply attach:


to any API Endpoint, and the result set will be returned wrapped in the callback function you specified.

Example query:


Not sure about what JSONP does? Here's a helpful Stack Overflow thread.

Example response:

  "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:

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

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

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

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

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.


Code Examples


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

// Decode JSON response:
$validationResult = json_decode($json, true);

// Access and use your preferred validation result objects

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


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.

Plan Name Monthly Price Number of Calls Overage Price per call Overage Total price
Basic $14.99 2,500 0.0071952 500 $18.59
Professional $59.99 25,000 0.00287952 5000 $74.39
Enterprise $129.99 60,000 0.0025998 12,000 $161.19

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.