Validation API

Introduction

Our V2 API is a synchronous & asynchronous bulk API focused on ease of use, providing simple validation for various types of information - using extended checks for the best result, and falling back to our own syntax checking so a temporary failure upstream (e.g. HLR, Landline) never produces an incorrect result.

You don't need a registered account to use this API, but you'll be limited to 10 free syntax checks a day. Register an account and set up a token and that rises to 100 free syntax checks a day. All paid checks (HLR, Landline & Email) include the syntax result free of charge and are never rate-limited.

Considerations

Before integrating with this API, the following should be considered:

• Treat your account details and credentials as secret - you are responsible for every request submitted.
• Every submission to the system is audited for management and security purposes.
• Submitting duplicate lookups bills your account for each individual submission.

Authentication

Set up an API token under Profile → API Authentication. Make sure to use the right token for the use case, and never expose a private token to an end user. All requests go to https://api.datasoap.co.uk over SSL (port 443).

Authorization: Bearer f07772e880ae4789b5a964c91a151a...

Authorization check

A simple check to see if your token is working:

{ "authorised": true }

Balance enquiry

Check your remaining credits per product type before running a job.

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

Validation checks

Pass any combination in the checks array. Auto detects the lookup type and runs the right checks. Every paid check also returns a free Syntax result as a fallback.

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

Response headers

Running anything beyond a syntax check also reports credits used per check, in the response headers:

• X-TPS-Credits-Used
• X-Landline-Credits-Used
• X-HLR-Credits-Used
• X-MNP-Credits-Used
• X-Email-Credits-Used

Results

Every lookup returns a syntax result even when it wasn't requested - so if a live check is inconclusive, you still have something to make a decision on. Running syntax on its own also returns suggestedChecks: the further checks we'd recommend for that record.

{
  "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"]
}

HLR (mobile validation)

A live lookup against the mobile network's Home Location Register - a real-time result for the number's status.

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

MNP (mobile number portability)

A live lookup returning the original network a number was allocated to, and the current (ported) network if it has moved.

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

TPS / CTPS

Checks a number against the UK's Telephone Preference Service (TPS) and Corporate TPS (CTPS) registers.

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

Landline

"landline": {
  "active": "LikelyAlive"
}

Email

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