API Documentation

Phoneverify API

Phoneverify’s RESTful JSON API is a fully functional and simple service for national and international phone numbers validation and information search in 232 countries worldwide.

The requested numbers are processed in real time and checked according to the most up-to-date databases of international numbering plans, and returned in a user-friendly JSON format where you can find information about carrier, geographic location and line type data.

Specifications and overview

API access key and authentication

After registration, each user gets a personal API access key — a unique "password" that is used to make API requests.

To authenticate with the Phoneverify API, you need to attach your key to the base endpoint URL:

https://phoneverify.online/verify?key=YOUR_ACCESS_KEY

How to make an API request?

As all existing validation data is returned by the same main API endpoint, the process of a phone number validation request to Phoneverify API is pretty easy.

The simplest API request:

Take a look at the following API request URL: (If you want to try it by yourself, first, you need to get the free access plan and to attach your Access Key to the URL)

As you can see, as part from the key parameter, there is only one required parameter (phone) to start the process of phone numbers validation.

Optional parameters:

API response

All Phoneverify validation data is returned in common and lightweight JSON format. The standard set of API results is below:

{
    "valid":true,
    "number":"16206151444",
    "local_format":"6206151444",
    "international_format":"+16206151444",
    "country_prefix":"+1",
    "country_code":"US",
    "country_name":"United States of America",
    "location":"Hutchinson (Kansas)",
    "carrier":"Cellco Partnership (Verizon Wireless)",
    "line_type":"mobile"
}

                    

API response objects:

There are 9 separate JSON response objects in each API response.

Paid customers can set up a secure connection (industry-standard SSL) to the Phoneverify API and all data given and available through it.

API Error Codes

Should your query fail, the Phoneverify API will return a three-digit error code, as well as an internal error type, and a plain text "info" object that contains suggestions for the user.

Below is an example of an error that occurs when no phone number was specified:

{
    "success": false,
    "error": {
        "code": 210,
        "type": "no_phone_number_provided",
        "info": "Please specify a phone number. [Example: 16206151444]"
    }
}

                    

Common API errors:

JSONP Callbacks

The Phoneverify API supports JSONP callbacks. In order use this feature, just attach the following:

callback = CALLBACK_FUNCTION

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

Request example:

https://phoneverify.online/verify?callback=CALLBACK_FUNCTION

Not sure how JSONP functions? Here is a useful Stack Overflow thread.

Example response:

CALLBACK_FUNCTION ({
{
    "valid":true,
    "number":"16206151444",
    "local_format":"6206151444",
    "international_format":"+16206151444",
    "country_prefix":"+1",
    "country_code":"US",
    "country_name":"United States of America",
    "location":"Hutchinson (Kansas)",
    "carrier":"Cellco Partnership (Verizon Wireless)",
    "line_type":"mobile"
}
})

                    

API Features

Number Validation

The process of a phone number validation request in the Phoneverify API is easy. Just add the number parameter followed by the phone number you want to validate to the API check endpoint.

Example query:

Look at the following API request url: (If you want to try it out, get the Free Plan and attach your Access Key to the URL)

Number input formats and correction mechanisms:

Country and Location Data

Each valid phone number request contains the following information: a two-digit country_code, three geographic identifiers, the corresponding full country_name, and an individual location object like the city, state, or county where the requested phone number is registered.

[...]
"country_code":"US",
"country_name":"United States of America",
"location":"Hutchinson (Kansas)",
[...]

                    

National (Local) Numbers

If you want to specify a phone number in its national (local) format, you will need to provide additional country information. Please, add your preferred two-digit country code to the API country_code parameter and include it in the API request URL.

Important: When working with national phone numbers, you must specify the country code.

Carrier Detection

Phone numbers assist businesses with identifying and legitimizing customers. Some numbers are very easy to obtain from certain carriers. For example, literally anyone can quickly register numerous phone numbers with a free online provider and create fake profiles at ease.

To eliminate this risk, the Phoneverify API will return a separate carrier object containing the name of the carrier the requested phone number is registered with. Thus, companies may require additional authentication for carriers associated with more incidences of fraud.

[...]
"carrier":"Cellco Partnership (Verizon Wireless)",
[...]

                    

Line Type Identification

Some types of numbers do not accept all kind of communication, for example, many VoIP numbers and landlines numbers do not accept SMS messages. This is why the Phoneverify API will identify the number's line type and return a line_type JSON object that contains the necessary information so you can identify what kind of communication the number can accept.

[...]
"line_type":"mobile"

                    

Being aware of a phone number line type eases the decision-making process whether it is better to send voice or text messages and ensures full compliance with the FCC Telephone Consumer Protection Act (TCPA).

Line types:

Please find a list of all linetypes supported by the API below.

Countries Endpoint

The Phoneverify API supports phone number validation for 232 countries (territories) around the world in total. API's countries endpoint will help you to access a list of supported areas, including country names and dialing codes.

{
    "AF":{
    "country_name":"Afghanistan",
    "dialling_code":"+93",
    },
    "AL":{
    "country_name":"Albania",
    "dialling_code":"+355",
    },
    "AF":{
    "country_name":"Algeria",
    "dialling_code":"+213",
    },
[...]

                    

Please add your private API access key to the countries endpoint to access this JSON file.

Code Examples

PHP (cURL)

Validate phone number:

Please, find a way of using PHP (cURL) to verify a phone number below:

// set API Access Key
 $access_key = 'YOUR_ACCESS_KEY';

// set phone number
$phone = '16206151444';

// Initialize CURL:
$ch = curl_init( 'https://phoneverify.online/verify?key='.$access_key.'&phone='.$phone);
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:

Please, find a way of using jQuery.ajax to verify a phone number below:

// set endpoint and your access key
var access_key = 'YOUR_ACCESS_KEY';
var phone = '16206151444';

// verify phone number via AJAX call
$.ajax({
    url: 'https://phoneverify.online/verify?key=' + access_key + '&phone' + phone,
    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);

    }
});