Validation Api

Test the API

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
}
or
{
    "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,
        "mps": 338,
        "paf": 818,
        "syntax": 17,
        "tps": 742,
        "unsubscribe": 500
    }
}

Validation Checks

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

Body

{
  "lookup": "441502569004",
  "checks": [
    "Auto","Hlr", "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

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-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.

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 lookups

Code

T or P

Description

-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.