API Documentation

API Access Key & Authentication

After registration, each user gets a personal API Access Key — a unique "password" used to make API requests.

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

How to make an API request

As all validation data is returned by the same main API endpoint, requesting a phone number validation from the Phoneverify API is straightforward.

The simplest API request

Take a look at the following API request URL. To try it yourself, first get the free access plan and attach your Access Key to the URL:

As you can see, apart from the key parameter, there is only one required parameter — phone — to start the validation process.

Optional parameters

API Response

All Phoneverify validation data is returned in a common, lightweight JSON format. The standard set of API results looks like this:

{
    "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.

256-bit HTTPS Encryption

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

To make your connection secure, simply add an s to the HTTP protocol — the result is https://

API Error Codes

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

Below is an example of an error that occurs when no phone number is 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 (JSON with padding) callbacks. To use this feature, simply attach the following to any API endpoint:

The result set will be returned wrapped in the callback function you specified.

Request example

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

Number Validation

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

Example query

Take a look at the following API request URL. To try it yourself, get the Free Plan and attach your Access Key to the URL:

Number input formats

It is more efficient to provide phone numbers in a strictly numeric format — for example, 16206151444.

Country & Location Data

Each valid phone number request returns a two-digit country_code, the corresponding full country_name, and an individual location object — such as 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'll need to provide additional country information. Add your preferred two-digit country code to the API country_code parameter and include it in the request URL.

Carrier Detection

Phone numbers help businesses identify and legitimize customers. Some numbers are very easy to obtain from certain carriers — literally anyone can quickly register numerous numbers with a free online provider and create fake profiles with ease.

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

// ...
"carrier": "Cellco Partnership (Verizon Wireless)",
// ...

Line Type Identification

Some types of numbers don't accept all kinds of communication — for example, many VoIP and landline numbers don't accept SMS messages. That's why the Phoneverify API identifies the number's line type and returns a line_type JSON object so you can determine what kind of communication the number can accept.

// ...
"line_type": "mobile"

Knowing a phone number's line type eases the decision of whether to send voice or text messages, and helps ensure full compliance with the FCC Telephone Consumer Protection Act (TCPA).

Supported line types

Countries Endpoint

The Phoneverify API supports phone number validation for 232 countries (territories) around the world. The API's countries endpoint gives you access to 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"
    },
    "DZ": {
        "country_name": "Algeria",
        "dialling_code": "+213"
    },
    // ...
}

Add your private API Access Key to the countries endpoint to access this JSON file.

Code Examples

Below are minimal examples of validating a phone number using PHP (cURL) and JavaScript (jQuery.ajax).

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

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

// Initialize CURL:
$ch = curl_init( 'https://phoneverify.online/api/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'];

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

    }
});