PLEASE NOTE: This article is intended for developers. If you require assistance, please contact us.
The API is avaliable at:
https://vapi.databowl.com/api/v1/validation
HLR
To validate a phone number submit a HTTP GET request to the API with the following parameters:
Parameter | Value | Description |
service | validate | -- |
type | hlr | -- |
data[mobile] | The mobile number to check | Specify the mobile phone number you wish to run the check against. To check a non-UK mobile you must prefix the number with a + and then the country code, e.g: +354xxxxxxxxxx. Numbers not starting with a + will be processed as a UK mobile. |
You must also pass the appropiate authentication parameters, please see the authentication section below.
The result will be a JSON string in the following format:
{ "result": "-result-", "network": "-network-" }Possible values for result are:
Value | Description |
live | The number is live and valid. The |
dead | The number is not live or invalid. |
retry-later | It is not possible to determine if a phone number is live at this time. This is most frequently caused by the subscriber's device being turned off. You should try again in a few hours. |
Please note that the network result is only included for live numbers.
LLV
To validate a UK landline submit a HTTP GET request to the API with the following parameters:
Parameter | Value | Description |
service | validate | -- |
type | llv | -- |
data[phone] | The UK landline number to check | Specify the UK landline number you wish to run the check against. |
You must also pass the appropiate authentication parameters, please see the authentication section below.
The result will be a JSON string in the following format:
{ "result": "-result-" }Possible values for result are:
Value | Description |
live | The landline number is live and valid. |
dead | The landline number is not live or invalid. |
retry-later | It is not possible to determine if a landline is live at this time. You should try again in a few hours. |
To validate a email address submit a HTTP GET request to the API with the following parameters:
Parameter | Value | Description |
service | validate | -- |
type | -- | |
data[email] | Email Address | Email Address |
You must also pass the appropiate authentication parameters, please see the authentication section below.
The result will be a JSON string in the following format:
{ "result": "-result-" }The result will be true if the validation is successful, otherwise it will contain an error message.
PAF
To validate a UK address submit a HTTP GET request to the API with the following parameters:
Parameter | Value | Description |
service | lookup | -- |
type | paf | -- |
data[postcode] | UK Postcode | Postcode |
You must also pass the appropiate authentication parameters, please see the authentication section below.
The result will be a JSON string in the following format:
{ "result": "-result-", "pafAddress": { address1: "-address line one-", address2: "-address line two-", address3: "-address line three-", address4: "-address line four-", town: "-town-", county: "-county-", postcode: "-postcode-", premises: [ { organisation: "-organisation-", building: [ '-building details-', ... ], number: "-number-" }, ... ] } }The result will be true if the lookup is successful, otherwise it will contain an error message.
Mobile Payment Type
To retreive the mobile payment type for a given mobile number submit a HTTP GET request to the API with the following parameters:
Parameter | Value | Description |
service | lookup | -- |
type | mobile_payment_type | -- |
data[mobile] | The mobile number to check | Specify the mobile phone number you wish to run the check against. Note, it should be in the format: 44xxxxxxxxx |
data[network] | The mobile network that the phone number is currently on (optional) | Optionally, you can specify the mobile phone network that the phone number is currently on. This parameter is optional but if it is not provided then a HLR check will be ran against the provided phone number in order to determine the network. |
You must also pass the appropiate authentication parameters, please see the authentication section below.
Currently supported networks are Orange, O2 and T-Mobile. If you pass the data[network] parameter then it must be one of the supported networks. If you don't pass the network then the mobile network will be aquired using HLR. The mobile payment type check won't be performed if the mobile network is not supported but you will still be charged for the HLR check.
The result will be a JSON string in the following format:
{ "error": "", "result": "" }The payment_type will be either Contract or PAYG if the request was successful. Otherwise error will indicate the error.
Authentication
In order to use the Validation API you must authenticate yourself. In order to authenticate you'll need both your public and private API keys which will be provided to you.
To authenticate you need to pass three query parameters to the API: key, timestamp, and signature. The key parameter is your public key, timestamp the current number of seconds since the unix epoch (GMT), and signature is a SHA-256 HMAC hash generated as described below.
To generate the value for signature you should first take the timestamp, service, and type parameters and format them as below:
timestamp=<timestamp>&service=<service>&type=<type>
Then, append the data (dependant on the service and type) to the string. For example if you pass two items of data, mobile and network then you'd format the string like so:
timestamp=<timestamp>&service=<service>&type=<type>&data[mobile]=<mobile>&data[network]=<network>
Then compute the HMAC of this string using SHA-256 as the hashing algorithm and your private API key as the key. The result of this must be repesented in lowercase hexits. This result then can be used as the signature parameter.
For example, using the Mobile Payment Type lookup service with a mobile number of 441234567890 the string you'd compute the HMAC of would be:
timestamp=1391437190&service=lookup&type=mobile_payment_type&data[mobile]=441234567890