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:
https://api.apilayer.net/numverify/validate?access_key=YOUR_ACCESS_KEYMake 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.
Take a look at the following API request URL:
https://api.apilayer.net/numverify/validate?access_key=YOUR_ACCESS_KEY&number=14158586273As you can see, in addition to the access_key parameter, there is only number required parameter 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
All Customers may establish a secure connection (using industry-standard SSL) to the numverify API and to 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 |
|---|---|---|
| 101 | "missing_access_key" | User did not supply an Access Key. |
| 101 | "invalid_access_key" | User entered an invalid Access Key. |
| 102 | "inactive_user" | The user's account is not active. User will be prompted to get in touch with Customer Support. |
| 103 | "invalid_api_function" | User requested a non-existent API function. |
| 104 | "usage_limit_reached" | User has reached or exceeded his Subscription Plan's monthly API Request Allowance. |
| 105 | "https_access_restricted" | The user's current Subscription Plan does not support HTTPS Encryption. |
| 106 | "rate_limit_reached" | User has exceeded the maximum rate limitation allowed on his subscription plan. |
| 210 | "no_phone_number_provided" | User did not provide a phone number. |
| 211 | "non_numeric_phone_number_provided" | User did not provide a numeric phone number. |
| 310 | "invalid_country_code" | User provided an invalid 2-letter country code. |
| 404 | "404_not_found" | User requested a resource which does not exist. |
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:
https://api.apilayer.net/numverify/validate?access_key=YOUR_ACCESS_KEY&number=14158586273&callback=CALLBACK_FUNCTIONNot 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
To enhance readability, the Numverify API includes a built-in JSON formatter that displays the API's Response in a typical JSON format.
To enable this function, simply attach format=1 to any valid API request URL:
https://api.apilayer.net/numverify/validate?access_key=YOUR_ACCESS_KEY&number=14158586273&format=1Please 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.