API Documentation

INTRODUCTION

Veriphone is a REST based JSON API.

It provides a set of stateless endpoints that any program or web browser can call by sending a standard HTTP request. veriphone will respond with a standard HTTP response carrying a JSON payload. This documentation describes these endpoints, their input/output parameters and authentication methods.


AUTHENTICATION

Veriphone endpoints support two authentication methods, key based and domain based authentication.

Key Based Authentication

Veriphone will respond to requests carrying the HTTP parameter key. The key parameter must contain a 32-character chain that registered users can copy from their control panel.

Example
https://api.veriphone.io/v1/verify?key=712E59151C8B4D1DB593D43678ABBF47
Domain Based Authentication

Veriphone will allow all requests coming from authorized domains. You can authorize your domain on your control panel.


ERRORS

Veriphone uses standard HTTP status codes to indicate the success or failure of a request. Successful requests will receive a 200 response code, while responses with a 40x or 500 indicate a failure.

400
Bad request
Returned if a required input parameter is missing.
401
Unauthorized
Returned if the request is coming from an unauthorized domain and the key parameter is missing or not valid.
403
Forbiden
Indicates that the key or domain used is inactive. This usually happens if a usage quota is exceeded or a payment is overdue.
500
Server error
Internal server error. Indicates a failure on veriphone servers. Although these are rare, if you get one please report it on live chat

VERIFY

Veriphone's verify endpoint takes a phone number and an optional default-country as input, and tells you if the number is valid.

For valid numbers, it will also return the number's type (mobile, land line, toll free, etc...) the carrier and other fields as described in the output section bellow.

If the number does not start with a country prefix, indicated by a leading '+', the number will be cheked against the default-country's numbering scheme. If no default-country is provided, a country will be infered from the IP address originating the request.

URL
https://api.veriphone.io/v1/verify
Method GET POST
Input
key
String
Authentication key
(optional if sent from an authorized domain)
phone
String
A phone number
default_country
2 characters
The default country in a 2 letters ISO format. Example: US, RU.
Optional: the country will be infered from the prefix, from this parameter or from the IP address (in that order).
Output
status
String
Status indicating the success or failure of the request execution. Values: success, error
phone
String
The phone number provided as input.
phone_valid
true/false
True if the phone number provided is valid.
phone_type
String
The phone number's type. Values: fixed_line, mobile, unknown, fixed_line_or_mobile, toll_free, premium_rate, shared_cost, voip
phone_region
String
Country region corresponding to the phone number. Empty for mobile numbers.
country
String
Name of the country corresponding to the phone number. Example: Canada, Netherland
country_code
2 characters
2 letters ISO code of the country corresponding to the phone number. Example: CA,NL
country_prefix
String
International country dialing code. Example: 32, 971
international_number
String
The phone number in the intenational format, with a leading + sign. Example: +49 1512 3577723
local_number
String
The phone number in local dialing format. Example: 01512 3577723
e164
String
The phone number in standard E164 format, with a leading + sign. Example: +4915123577723
carrier
String
Name of the carrier providing the phone number.
Request
https://api.veriphone.io/v1/verify?phone=%2B49-15123577723&key=266B0091BC9547A2A40DD088795FA4C6
Response
{
  "status": "success",
  "phone": "+49-15123577723",
  "phone_valid": true,
  "phone_type": "mobile",
  "phone_region": "Germany",
  "country": "Germany",
  "country_code": "DE",
  "country_prefix": "49",
  "international_number": "+49 1512 3577723",
  "local_number": "01512 3577723",
  "e164": "+4915123577723",
  "carrier": "T-Mobile"
}

EXAMPLE

Veriphone's example endpoint returns an example (dummy) phone number for any country/phone-type combination.

The country and phone type are optional. If no country is specified , a country will be infered from the IP address originating the request.

If no phone type is specified, 'mobile' will be used as default type

URL
https://api.veriphone.io/v1/example
Method GET POST
Input
key
String
Authentication key
(optional if sent from an authorized domain)
type
String
The type of example number to return. Values: fixed_line, mobile , premium_rate, shared_cost, toll_free, voip
Optional: will default to mobile
country_code
2 characters
The example number's country in a 2 letters ISO format. Example: US, RU.
Optional: the country will be infered from the IP address if this parameter is absent or invalid.
Output
status
String
Status indicating the success or failure of the request execution. Values: success, error
phone_type
String
The example phone number's type. Values: fixed_line, mobile, toll_free, premium_rate, shared_cost, voip
country_code
2 characters
2 letters ISO code of the country corresponding to the phone number. Example: CA,NL
country_prefix
String
International country dialing code. Example: 32, 971
international_number
String
The example phone number in the intenational format, with a leading + sign. Example: +49 1512 3577723
local_number
String
The example phone number in local dialing format. Example: 01512 3577723
e164
String
The example phone number in standard E164 format, with a leading + sign. Example: +4915123577723
Request
https://api.veriphone.io/v1/example?type=fixed_line&country_code=FR&key=266B0091BC9547A2A40DD088795FA4C6
Response
{
  "status": "success",
  "phone_type": "fixed_line",
  "country_code": "FR",
  "country_prefix": "33",
  "international_number": "+33 1 23 45 67 89",
  "local_number": "01 23 45 67 89",
  "E164": "+33123456789"
}