Synchronous API

Currently the synchronous API supports the following validation checks.

HLR (Home Location Register)
Landline
TPS (Telephone Preference Service)
Unsubscribe
Email
MPS (Mailing Preference Service)

How it works

Foremost the API is synchronous, that means once a request is sent no data will be returned back until the request is finished.

Simply put, a HTTP request is made by the client server to the API and once the validation is complete the result is returned directly back. Meanwhile the server has to wait for the response.

Considerations

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

There is no restriction on the number of parallel submissions that can be made to the API. However, should issues present due to high levels of traffic from an individual then a throttling limit may be placed on certain IP addresses in order to reduce system throughput.
All account details and credentials should be treated as confidential as the client is responsible for all 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
Because of the nature of some of the lookup types namely HLR, some submissions may result in a heavily delayed response. However, a correctly formatted lookup usually returns a result in less than a second in the majority of cases.

API

The first step is to setup an API password which can be set from your accounts profile section, By default access to the API is denied until a password is set. 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 them from the bundles page.

Making Requests

All API requests should be made to api.datasoap.co.uk using SSL on port 443, The account credentials and lookup details need to be appended as a query string. The API will always return a 200 (OK) response.

URL

https://api.datasoap.co.uk/?output=json&number={Number}&type={Type}&validationEmail={Email}&validationAddress={Address}&validationName={Name}

Headers:

Authorization: Token {Token}

URL Parameters

Name	Optional?	Description	Examples
Output	No	The output format, keep this as JSON (Our recommend format)	JSON
Account	No	The account owners current email address	joe.b@datasoap.com
Password	No	Current password for the account	#101#DataSoap
Type	No	The type of lookup	HLR, Landline, TPS, Unsubscribe, Email, MPS
Number	Yes	Phone number to lookup	0207 856 0422
ValidationEmail	Yes	Email address to lookup	joe.b@datasoap.co.uk
ValidationAddress	Yes	Postal address to lookup	61 Alexandra Road, Lowestoft, Suffolk, NR32 3LQ.
ValidationName	Yes	Name to lookup	Joe Bloggs

Note: The output format should be kept as JSON, as this is our supported and recommended format. We also support XML, however this documentation is geared towards JSON.

HTTP Responses

Each lookup type has its own response model and as such our response format has a 2 tier JSON container format which indicates the type of response. The first tier 'DataSoapAPIResponse' indicates a response from our API and the second tier is for the type of lookup result e.g.

                {
"DataSoapAPIResponse": {
"HlrLookupResult": {
}
}
}

In the event of an error the response will have a field 'ErrorCode' which is a numeric representation of a specific error that needs to be handled by the requestor. It is important that the ErrorCode is handled correctly. Error responses will look like the following:

    {
"DataSoapAPIResponse": {
"HlrLookupResult": {
"ErrorCode": -96
}
}
}

HTTP Response Details

TPS

The result of a successful TPS lookup will contain the following fields:

Field	Description
MSISDN	phone number checked (following normalisation)
TPS	Whether the phone number is registered with the Telephone Preference Service.
CTPS	Whether the phone number is registered with the Corporate Telephone Preference Service.
DNC	Whether the phone number is on our internal Do Not Call list.

Sample

Request Url:

https://api.datasoap.co.uk/?output=JSON&number={Number}&type=TPS

Request Headers:

Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=

Response:

{
"DatasoapAPIResponse": {
"TPSResult": {
"MSISDN": "00447976123456",
"TPS": true,
"CTPS": false,
"DNC": true,
"TPSID": 12032505
}
}
}

HLR

The result of a successful HLR lookup will contain the following fields:

Field	Description
MSISDN	mobile phone number checked (following normalisation)
MCC	The mobile county code
MNC	The mobile network code
CountryName	The name of the mobile country
NetworkName	The name of the mobile network
On	Whether the phone is recognised as live and switched on

Sample:

Request Url:

https://api.datasoap.co.uk/?output=JSON&number={Number}&type=HLR

Request Headers:

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

MPS

The result of a successful MPS lookup will contain the following fields:

Field	Description
OnMps	Whether the address being looked up was present on the MPS
DateRequested	The date the record was registered with the MPS
MatchLevel	The level of matching: *ExactMatch* - The full name and address matched a record on the MPS *PartialMatch* - The address matched but the name only partially matched *LowMatch* - The address matched but the name did not. *NoMatch* - The address did not match. *MoreDataRequired* - There was not enough data to give an accurate match.

Sample

Request Url:

https://api.datasoap.co.uk/?output=JSON&validationAddress={Address}&validationName={Name}&type=MPS

Request Headers:

Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=

Response:

                {
"DatasoapAPIResponse": {
"MpsResult": {
"OnMps": true,
"DateRequested": "01/01/2000",
"MatchLevel": "ExactMatch"
}
}
}

Landline

The result of a successful Landline lookup will contain the following fields:

Field	Description
Number	The landline number checked (following normalisation)
IsActive	Whether the landline number was active

Sample

Request Url:

https://api.datasoap.co.uk/?output=JSON&number={Number}&type=Landline

Request Headers:

Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=

Response:

         
                {
"DataSoapAPIResponse": {
"UnsubscribeResult": {
"MSISDN": "00442078560422",
"IsActive": true
}
}
}

Email

The result of a successful Email lookup will contain the following fields:

Field	Description
Email	Email checked (following normalisation)
User	The domain user identifier
IsHighQuality	Whether the email was determined as high quality
Reason	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
IsFree	Whether the email is recognised as part of a free provider service such as Gmail or Yahoo! Mail
UsDisposable	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.
IsRole	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.
AcceptsAll	Whether the email server just accepts all email regardless of recipient.

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.

Sample

Request Url:

https://api.datasoap.co.uk/?output=JSON&validationemail={Email}&type=Email

Request Headers:

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

An unsuccessful email query will result in an error response. An example is below. Detail on the error codes can be found in the Error Codes section.

Error Sample

                
                {
"DatasoapAPIResponse": {
"EmailValidationResult": {
"Email": "test@example.com",
"ErrorCode": -26,
"Reason": "No Connect"
}
}
}

Unsubscribe

The result of a successful Unsubscribe lookup with contain the following fields:

Field	Description
MSISDN	The phone number checked (following normalisation)
OnCompany	Whether the phone number was on the account owners unsubscribe list
OnCompanyDateAdded	The date which the number was added to the account owners unsubscribe list
OnGlobal	Whether the phone number was on Liquid11's global unsubscribe list
OnGlobalDateAdded	The date which the number was added to the global unsubscribe list

Note:

The field 'OnGlobal' and 'OnGlobalDateAdded' are only available if the global unsubscribe feature is enabled on the account by a member of the datasoap team.

Sample

Request Url:

https://api.datasoap.co.uk/?output=JSON&number={Number}&type=Unsubscribe

Request Headers:

Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=

Response:

    
{
"DataSoapAPIResponse": {
"UnsubscribeResult": {
"MSISDN": "00442078560422",
"OnCompany": false,
"OnCompanyDateAdded": null
}
}
}

Generic 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 Liquid11" 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. Typically less than 1% of requests will return this error. 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 Liquid11" 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.

Synchronous API

The Data Soap synchronous API allows clients to perform individual lookups using our data validation service. This guide is made available to provide the necessary technical information to integrate Data Soaps services into our client's bespoke systems.

Looking for something else?

Synchronous API

URL

Headers:

URL Parameters

HTTP Response Details

Sample

Sample:

Sample

Sample

Sample

Error Sample

Sample

Email Lookups

Api Test

HTTP Request

Authentication Header

Request Parameters

Request Body

Status

Response Body

Webhook

The Data Soap synchronous API allows clients to perform individual lookups using our data validation service.
This guide is made available to provide the necessary technical information to integrate
Data Soaps services into our client's bespoke systems.