API Documentation v2

INTRODUCTION

Veriphone API 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 API uses API keys to authenticate requests. You can view and manage your API key in your control panel.

Requests carrying your API key will deduct 1 credit from your balance, so be sure to keep your key secure! Do not share it in publicly accessible areas such as GitHub or client-side code.

API requests without a valid API key will fail.

Example 
https://api.veriphone.io/v2/verify?key=712E59151C8B4D1DB593D43678ABBF47

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 or not valid.
401
Unauthorized		 Returned if the key parameter is missing or not valid.
402
Payment required		 Returned if no credits are available to cover the cost of the requested operation.
403
Forbiden		 Returned if access is not granted to the requested resource.
500
Server error		 Indicates a failure on veriphone servers. Although these are rare, if you get one please report it to support@veriphone.io

VERIFY

Veriphone's /v2/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/v2/verify
Method GET POST
Input
key
String		 Authentication key
phone
String		 A phone number
default_country
2 characters		 The default country in a 2 letters ISO code 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/v2/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 /v2/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/v2/example
Method GET POST
Input
key
String		 Authentication key
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/v2/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"
}