Data Soap
> LEGACY API

Synchronous API

The original Data Soap API for individual lookups - a request is made and the result is returned directly, with the caller waiting on the response.

Back to API list
BASE · https://api.datasoap.co.uk

Introduction

The synchronous API currently supports HLR (Home Location Register), Landline, TPS (Telephone Preference Service), MPS (Mail Preference Service), Email and Unsubscribe lookups. A request is made by your server and the API waits until validation is complete before responding - your server waits on the response.

Considerations

  • No restriction on parallel submissions, though a throttling limit may apply to an IP address under heavy traffic.
  • Treat account details and credentials as confidential - you're responsible for every request submitted.
  • Every submission is audited for management and security purposes.
  • Duplicate lookups are billed individually.
  • HLR lookups in particular can occasionally be delayed, though a correctly formatted lookup usually returns in under a second.

Looking for something else? See the Asynchronous API or the Batch API.

Getting started

Set up an API password from your account's profile section - by default API access is denied until a password is set. Make sure you have credits for the services you want to run; if not, purchase them from the bundles page.

Requests go to api.datasoap.co.uk over SSL (port 443), with credentials and lookup details appended as a query string. The API always returns a 200 (OK) response, with the result (or an error code) in the body.

URL
https://api.datasoap.co.uk/?output=json&number={Number}&type={Type}&validationEmail={Email}&validationAddress={Address}&validationName={Name}
Param
Required
Description
output
Yes
Output format - keep as JSON.
type
Yes
HLR, Landline, TPS, Unsubscribe, Email or MPS.
number
For phone lookups
The phone number to look up.
validationEmail
For email lookups
The email address to look up.
validationAddress
For MPS lookups
The postal address to look up.
validationName
For MPS lookups
The name to look up.

TPS

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

Request
https://api.datasoap.co.uk/?output=JSON&number={Number}&type=TPS
Header
Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=
Response
{
  "DataSoapAPIResponse": {
    "TPSResult": { "MSISDN": "00447976123456", "TPS": true, "CTPS": false, "DNC": true, "TPSID": 12032505 }
  }
}
Field
Description
MSISDN
The phone number checked, after normalisation.
TPS
Whether the number is registered with the Telephone Preference Service.
CTPS
Whether the number is registered with the Corporate Telephone Preference Service.
DNC
Whether the number is on our internal Do Not Call list.

HLR

Request
https://api.datasoap.co.uk/?output=JSON&number={Number}&type=HLR
Header
Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=
Response
{
  "DataSoapAPIResponse": {
    "HLRResult": { "MSISDN": "00447976123456", "MCC": "234", "MNC": "10", "CountryName": "United Kingdom of Great Britain and Northern Ireland", "NetworkName": "UK - 02 (UK) Limited", "On": true }
  }
}
Field
Description
MSISDN
The mobile number checked, after normalisation.
MCC / MNC
The mobile country code and network code.
CountryName / NetworkName
The mobile country and network.
On
Whether the phone is recognised as live and switched on.

MPS

Request
https://api.datasoap.co.uk/?output=JSON&validationAddress={Address}&validationName={Name}&type=MPS
Header
Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=
Response
{
  "DataSoapAPIResponse": {
    "MpsResult": { "OnMps": true, "DateRequested": "01/01/2000", "MatchLevel": "ExactMatch" }
  }
}
Field
Description
OnMps
Whether the address was present on the MPS register.
DateRequested
The date the record was registered with the MPS.
MatchLevel
ExactMatch · PartialMatch · LowMatch · NoMatch · MoreDataRequired.

Landline

Request
https://api.datasoap.co.uk/?output=JSON&number={Number}&type=Landline
Header
Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=
Response
{
  "DataSoapAPIResponse": {
    "LandlineResult": { "MSISDN": "00442078560422", "IsActive": true }
  }
}
Field
Description
MSISDN
The landline number checked, after normalisation.
IsActive
Whether the landline number was active.

Email

Request
https://api.datasoap.co.uk/?output=JSON&validationemail={Email}&type=Email
Header
Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=
Response
{
  "DataSoapAPIResponse": {
    "EmailValidationResult": { "Email": "joe.b@datasoap.co.uk", "User": "joe.b", "Domain": "datasoap.co.uk", "IsHighQuality": false, "Reason": "Low Deliverability", "IsFree": false, "IsDisposable": false, "IsRole": false, "AcceptsAll": true }
  }
}
Field
Description
Email / User / Domain
The address checked, and its local part / domain.
IsHighQuality
Whether the address was determined high quality.
Reason
Safe to Send · Low Deliverability · Accepted Email · Low Quality.
IsFree / IsDisposable / IsRole
Free provider / disposable / role-based address flags.
AcceptsAll
Whether the mail server accepts all mail regardless of recipient.

An unsuccessful query returns an error code - see Error codes below.

Unsubscribe

Request
https://api.datasoap.co.uk/?output=JSON&number={Number}&type=Unsubscribe
Header
Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=
Response
{
  "DataSoapAPIResponse": {
    "UnsubscribeResult": { "MSISDN": "00442078560422", "OnCompany": false, "OnCompanyDateAdded": null }
  }
}
Field
Description
MSISDN
The phone number checked, after normalisation.
OnCompany / OnCompanyDateAdded
Whether - and when - the number was added to your own unsubscribe list.
OnGlobal / OnGlobalDateAdded
Whether - and when - the number was added to Data Soap's shared unsubscribe list (only present if that feature is enabled on your account).

Error codes

Common to all services

Code
Type
Description
-99
N/A
Token not recognised - use your API credentials, not your account login.
-98
N/A
Not enough credit on your account for this operation. Top up from the website or contact your account manager.
-97
Temporary
Unexpected error. Rare - we keep track of these on our side.
-96
Permanent
The value provided wasn't recognised as valid for the selected lookup type.
-92
Permanent
Account has exceeded the maximum lookups allowed for a non-verified account - contact support on 0207 856 0422.
-90
Temporary
You hit your own defined rate limit against this token.

HLR lookups

Code
Type
Description
-13
Permanent
Network data unavailable - the number hasn't been allocated to an active range.
-12
Temporary
The destination network isn't responding. Often temporary - retry.
-10 / -11
Temporary
No response within an acceptable timeframe. Retry; if it persists the number is likely dead.
-8
Permanent
Looked like a valid mobile number but was rejected as invalid by the network.
-7
Temporary
The network doesn't support SMS for this recipient.
-6
Permanent
Number is part of a closed user group (e.g. emergency services).
-5
Temporary
The destination network has blocked SMS for this recipient.
-4
Permanent
The recipient device doesn't support SMS.
-3
Permanent
A valid number that's not currently in use by the destination network.
-2
Temporary
Unexpected error, e.g. a signalling fault at the destination network. Rare.

Email lookups

Code
Type
Description
-29
Temporary
The SMTP server was unavailable to process the request.
-28
Temporary
The SMTP server returned an unexpected or 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 - it does not exist.
-21
Permanent
The domain either doesn't exist or isn't configured to receive email.

* Temporary error codes may return a different result if retried in quick succession, due to network fluctuations.

Trusted at scale

The same infrastructure behind every endpoint on this page, in production today.

0B+
Numbers validated
0K+
Batch cleans
0ms
p50 latency
0%
Uptime