Validation Api

How it works

Our V2 API is a synchronous & asynchronous bulk API which is focused on ease of use, providing simple validation service for various types of information, utilising various extended checks to ensure the best validation result, falling back on our home brewed syntax checking to ensure a temporary failure of an upstream check e.g. HLR, Landline does not yield incorrect results.

You do not need a registered account to use this API but you will be limited to 10 free Syntax Validation requests a day.

If you register an account and set up a token you will be able to run 100 free syntax checks a day.

All paid checks (HLR, Landline & Email) include the syntax results free of charge and are not limited.

Considerations

Prior to integrating with this Data Soap API, the following should be considered:

Your account details and credentials should be treated as secret because you are responsible for each requests submitted
Every submission to the system is audited for management and security purposes
In the case of submitting duplicate lookups the account will be billed for each, individual submission

API

Getting Started

The first step is to setup an API token which can be generated Under profile-> “API Authentication”, ensure you setup the correct token for the use and never expose a private token to an end user.

It is also important to ensure you have credits available for each validation service you wish to use. If you do not already have credits you can purchase these from within your account or calling us on 0203 856 0422.

Making Requests

All API requests should be made to https://api.datasoap.co.uk/ using SSL on port 443.

Headers:

Bearer Token:

f07772e880ae4789b5a964c91a151as1f1fee11d53as64807bd5f76f03b4333fa

The above token is an example and needs to be replaced with your token.

Authorization Check

A simple check to see if your Authorization Token is working

https://api.datasoap.co.uk/v2/authorised

Response

{
    "authorised": false
}

{
    "authorised": true
}

Balance Enquiry

Check you available balance of lookups for different product types.

https://api.datasoap.co.uk/v2/balance

Response

{
    "credits": {
        "email": 166,
        "hlr": 639,
        "landline": 21,
        "mnp": 902,
        "mps": 338,
        "paf": 818,
        "syntax": 17,
        "tps": 742,
        "unsubscribe": 500
    }
}

Validation Checks

https://api.datasoap.co.uk/v2

Body

{
  "lookup": "441502569004",
  "checks": [
    "Auto","Hlr","Mnp", "Tps", "Landline", "Email", "Syntax" 
  ]
}

Check Types

Auto – This will determine the lookup type automatically and run the appropriate validation methods.

Example:

A UK Landline Number will provide the following results: Syntax, Landline Validation & TPS
A UK Mobile Number will provide the following results: Syntax, HLR Validation & TPS
An Email Address will provide the following results: - Email Validation
An Email Address will provide the following results: - Email Validation

HLR – Does an HLR lookup check on a mobile phone number

MNP – Mobile Number Portability Check, this performs a MNP lookup returning the current network/ported network a mobile number may be allocated too.

TPS – Performs an Telephone Preference Service & Corporate Telephone Preference Service check on a number.

Landline – Perform landline validation on UK landlines only

Email – Preforms email validation

Syntax – This runs a syntax check on phone and email addresses

Response Headers

When running a further check, not a syntax check we will also return in the response header the amount of credits used in the following headers.

X-TPS-Credits-Used

X-Landline-Credits-Used

X-HLR-Credits-Used

X-MNP-Credits-Used

X-Email-Credits-Used

Results

All lookup types will return a syntax result even if it is not chosen, this is so that if the result live validation result is inconclusive you can make a decision based on the information provided by the Syntax result.

SYNTAX

The results will vary depending on what number type you enter and will provide information based around the number entered, the information is not live data and will not tell you if the number is live and available on if it is in a valid format and range of numbers.

If the syntax checks are run on their own, it will come back with suggested checks. These are further validation checks that we recommend are also run on that record.

Example Response

 
{
    "valid": true,
    "syntax": {
        "normalised": "+441502470922",
        "type": "Landline",
        "format": "E164",
        "additional": {
            "blockStatus": "Allocated",
            "originalProvider": "BT",
            "country": {
                "name": "United Kingdom of Great Britain and Northern Ireland",
                "numericCode": "826",
                "alpha2Code": "GB",
                "alpha3Code": "GBR"
            }
        }
    },
    "suggestedChecks": [
        "Landline",
        "Tps"
    ]
}

Field	Field Type	Returned Information	Detailed Information
Valid	Boolean	True/False	Based on information we hold or the live result information this will let you know if the number is valid. If a live HLR/Landline validation result is not performed a valid result will only mean that the number is from a valid range and not necessarily live.
Normalised	String	Phone Number	This will return the phone number in a normalized format
Format	String		This will return the format the phone number is normalized too. E.g. E164
Block Status	String		This tells you information based on the prefix allocation of that number range
OriginalProvider	Sting		This is the telephony provider that the phone number was originally allocated too, they may no longer be with this provider and have ported away
Location	String		This is the location of where that number range is allocated to.
Country - Name	String		The country where the number range belongs
Country – Numeric Code	Integer		ISO 3166-1 numeric code for that country
Alpha2code	Sting		3 character country code

Mobile validation (HLR Lookup)

An HLR will perform a live lookup with the mobile phone networks Home Location Register (HLR) database and provide a real-time result for the status of the phone number

Example Response

"hlr": {
    "mcc": 234,
    "mnc": 20,
    "networkName": "UK - 3",
    "on": true
}

Field	Field Type	Detailed Information
Mcc	Integer	The mobile country code for that number
Mnc	Integer	The mobile network code for that number
NetworkName	String	The network the phone number is currently allocated too.
On	Boolean	This tells you if the handset is currently turn on or switched off.

MNP Lookup (Mobile Number Portability Lookup

A MNP Lookup will perform a live lookup to the mobile phone networks and will provide a realtime result to see which network a mobile number is currently allocated to, it will return the original network and the ported network if it has ported.

Example Response

"mnp": {
        "original": {
            "networkName": "UK -Everything Everywhere Limited (Orange)",
            "mnc": 33,
            "mcc": 234
        },
        "ported": {
            "networkName": "UK - VODAFONE",
            "mnc": 15,
            "mcc": 234
        }
    }

Field	Field Type	Detailed Information
NetworkName	String	The network the phone number is currently allocated too.
Mcc	Integer	The mobile country code for that number
Mnc	Integer	The mobile network code for that number

TPS/CTPS

This service checks a lookup against data from TPS Online and will let you know if a phone number is on the UK’s Telephone Preference Service (TPS) & Corporate Telephone Preference Service (CTPS)

Example Response

"tps": {
        "tps": false,
        "ctps": false
    }

Field	Field Type	Detailed Information
TPS	Boolean	True – The number is on the TPS False – The number is NOT on the TPS
CTPS	Boolean	True – The number is on the CTPS False – The number is NOT on the CTPS

Landline

Example Response

"landline": {
        "active": true
    }

Field	Field Type	Detailed Information
Active	Boolean	If the number is active and live.

Email

Example Response

"email": {
        "user": "bryn.thompson",
        "domain": "gmail.com",
        "acceptsAll": false,
        "free": true,
        "disposable": false,
        "role": false,
        "highQuality": true,
        "reason": "Safe to Send",
        "valid": false
    }

Field	Field Type	Detailed Information
User	String	The domain user identifier
Domain	String	The domain of the email address
AcceptsAll	Boolean	Whether the email server just accepts all email regardless of recipient.
Free	Boolean	Whether the email is recognised as part of a free provider service such as Gmail or Yahoo! Mail
Disposable	Boolean	Whether the email is recognised as part of a disposable email service such as trashmail.com or mailinator.com, if this is case the email will likely expire shortly.
Role		Whether the email is recognised as a role based provider which is likely not a person but is likely associated with an automated process instead of a person.
Highquality	Boolean	Whether the email was determined as high quality
Reason	String	Reason for quality e.g. Low Quality - The email address is determined to have quality issues. It might be risky to send to this email address or it may be considered low value. Disposable, Accept All and role based emails are considered to be low quality Accepted Email - The SMTP server has accepted this email address Low Deliverability - Deliverability cannot be guaranteed for this email address Safe to send - This email address is safe to send too.
Valid	Boolean	If the email address is valid after live checks.

Note:

If the field IsHighQuality is set, there is very high probability of an emails to this address being delivered successfully.

Factors which might result in an email address NOT being considered high quality would be if it was a role based email address, a disposable email address or if the email domain accepts any emails sent to it. Emails sent to an address NOT considered to be High Quality are likely to bounce or result in low engagement, however because an email is not High Quality it does not mean that a real person might not be receiving it, for example most corporate email addresses will be catch all, thus will have a low quality.

Error Codes

Current error codes returned by the platform are:

Common to all services

Code	T or P	Description
-99	NA	Your password or your username wasn't recognised. Please ensure you are using your API credentials and not your account login details.
-98	NA	You do not have enough credit on your account for this operation. Please top-up using the website or by contacting your Account Manager
-97	* Temporary	"Please report to Data Soap" is usually seen when an unexpected error occurs. In small volumes these are not usually significant but we like to keep track of them. You should see very few of these.
-96	Permanent	The mobile number, landline number or email address provided for validation wasn't recognised as valid. Please ensure that the right lookup type is selected (e.g. HLR (Mobile Validation) is only for mobile numbers) and that the value is syntactically correct.
-92	Permanent	Your account has exceeded that maximum number of lookups allowed for a non-verified account, please contact support on 0207 856 0422
-90	* Temporary	You have hit your defined rate limit, This is a limit that you defined against the api token.

HLR / MNP lookups

Code	T or P	Description
-13	Permanent	Network data is currently unavailable for this number, which typically indicates that the number has not been allocated to an active range.
-12	* Temporary	The destination networks are not responding to queries. We recommend you try again as this is often a temporary occurrence
-10 or -11	* Temporary	The request was accepted but no response came back within an acceptable timeframe. For example, a number within a service centre that's too congested to answer. We recommend you retry this number, however if this error code is returned multiple times over a period of time it is likely the number is dead.
-8	Permanent	The number appeared to be a valid mobile number but it was rejected as invalid when submitted to the network.
-7	* Temporary	The network does not support SMS for the recipient. Most recipient devices resulting in this error will not support voice either although this is not guaranteed.
-6	Permanent	The mobile number is a member of a closed user group such as the emergency services.
-5	* Temporary	The destination network has blocked SMS for the recipient. Most recipient devices resulting in this error will not support voice either although this is not guaranteed.
-4	Permanent	The recipient device does not support SMS. Most devices with this error will not support voice either although this is not guaranteed.
-3	Permanent	A valid number that's not in use by the destination network at that time.
-2	* Temporary	"Please report to Data Soap" usually occurs when an unexpected error occurs such as a signalling fault at the destination network. In small volumes these are not usually significant but we like to keep track of them. You should see very few of these.

Email Lookups

Code	T or P	Description
-29	* Temporary	The SMTP server was unavailable to process the request
-28	* Temporary	The SMTP server returned an unexpected/invalid response
-27	* Temporary	The SMTP session timed out.
-26	* Temporary	Could not connect to the SMTP server.
-22	Permanent	The email address was rejected by the SMTP server and does not exist.
-21	Permanent	The domain name either does not exist or has not been configured to receive email.

* Temporary error codes may return a different result when tried a second time in quick succession due to network fluctuations.