API Access Key & Authentication
Specs & Overview
API Access Key
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.
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)
As you can see, in addition to the access_key parameter, there is only number required parameter to start validating phone numbers.
Optional parameters:
API Response
All numverify validation data is returned in universal and lightweight JSON format.
Find below a standard API result set:
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 (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:
Common API errors:
| Type | Message | Description |
|---|---|---|
| 403 | "missing_access_key" | User did not supply an Access Key. |
| 403 | "invalid_access_key" | User entered an invalid Access Key. |
| 404 | "404_not_found" | User requested a resource which does not exist. |
| 404 | "invalid_api_function" | User requested a non-existent API function. |
| 429 | "usage_limit_reached" | User has reached or exceeded his Subscription Plan's monthly API Request Allowance. |
| 601 | "no_phone_number_provided" | User did not provide a phone number. |
| 602 | "non_numeric_phone_number_provided" | User did not provide a numeric phone number. |
| 603 | "invalid_country_code" | User provided an invalid 2-letter country code. |
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:
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 a typical 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.