Getting Started
API Access Key & Authentication
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" |
256-bit HTTPS Encryption
Get free API Access Key
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:
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:
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
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:
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.