Data Cleaning API Documentation

Learn how to use our API

Introduction

The Data Soap API enables clients to undertake single number lookups to mobile networks, and to query whether a number is registered with the Telephone Preference Service (TPS) via a simple HTTP single line POST or GET.

This guide provides technical information for clients to assist them in interfacing with the Data Soap system and lists the responses that the client can expect to see from the system.

Considerations

Prior to use of the Data Soap system, the following should be considered:

1. There is no restriction on the number of parallel submissions that a client may make to the Liquid11 servers. However, should a client present high levels of traffic then a throttle may be placed on certain IP addresses which will reduce system throughput.

2. The client should ensure that all account details are treated as confidential and are responsible for all requests submitted.

3. All submissions to the system are audited for account management and security purposes.

4. If you submit a mobile or landline phone number for checking multiple times then your account is billed for each, individual submission.

5. Concerning HLR: Submission of a number which is not known by any network will result in a delayed response, usually in excess of eight seconds. Correctly formatted numbers will return a result within three seconds in 99.99% of cases. We recommend a time-out of five seconds is used when running a real-time verification system, after which the number being checked should be considered invalid. If your application is not time critical then all results will be returned within twelve seconds, and any returned after this you should consider the number being checked as invalid.

Calling the API

Credentials

To use the Data Soap API you will need a Data Soap login username and API password. The username will be the same as the login username you provided during registration for the Data Soap web site.

Please note: The API password is separate to your Data Soap account password. You can set your API password by logging into your account at https://www.datasoap.co.uk, and filling in the API password field on your Account Profile.

In the example URL's provided below we use beginning and closing braces '{' and '}' to indicate placeholder values, these braces should not be included in any requests to the Data Soap API and will result in an error if submitted.

API Quick Start

You will need Data Soap credits for the service you wish to use. If you do not already have credits you can purchase them from the bundles page.

Data Soap has a page which you can use to test the various API services easily, if your new to the API it's worth looking at this first as it provides the quickest way to get up and running. To access the page click here

URL

Clients should make calls to Data Soap via port 80. The IP address obtained for this URL via DNS should not be used, as IP addresses may change and the Liquid11 servers will reject the requests.

Sample URL:

https://api.datasoap.co.uk/?msisdn={MSISDN}&account={account}&password={password}&type={lookup}&output={output}

MSISDN = The mobile number to check
Account = Your account address username (email address)
Password = Your account password
Type = The lookup type, (either TPS or HLR)
Output = The data response format, use either ‘JSON’, ‘XML’ or omit the field entirely to use a delimited format)

HLR Lookup

To perform an HLR lookup use the above URL and specify HLR for the ‘type’ field. Excluding this field will also perform an HLR lookup automatically as it is assumed by default.

The result returned for an HLR lookup will contain the following:

MSISDN = The mobile phone number checked (following normalisation)
MCC = The Mobile Country Code
MNC = The Mobile Network Code
CountryName = The Mobile Country Name
NetworkName = The Network Name
On = Whether the phone is recognised as live and switched on

The values returned will be formatted in either JSON, XML or delimited depending on the "output" parameter and what was originally requested.

JSON OUTPUT:

When using the HLR lookup type with JSON data format the following is returned

Sample URL:

            
https://api.datasoap.co.uk/?msisdn={MSISDN}&account={account}&password={password}&type={lookup}&output={output}

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

XML OUTPUT

When using the HLR lookup type with XML data format the following is returned

Sample URL:

https://api.datasoap.co.uk/?msisdn={MSISDN}&account={account}&password={password}&type=HLR&output=xml

Sample Response:

<DatasoapAPIResponse 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <HLRResult>
        <MSISDN>
             00447976123456
        </MSISDN>
        <MCC>
             234
        </MCC>
        <MNC>
             10
        </MNC>
        <CountryName>
            United Kingdom of Great Britain and Northern Ireland
        </CountryName>
        <NetworkName>
            UK - 02 (UK) Limited
        </NetworkName>
        <On>
            True
        </On>
    </HLRResult>
</DatasoapAPIResponse>

DELIMITED OUTPUT:

When using the HLR lookup type with comma delimited data format the following is returned Sample URL:

Sample URL:

https://api.datasoap.co.uk/?msisdn={MSISDN}&account={account}&password={password}&type=HLR

Sample Response:

LQ|00447976123456|234|10|United Kingdom of Great Britain and Northern Ireland|UK - 02 (UK) Limited|1|

First field - LQ - This is our prefix and can be ignored
Second field - The mobile number checked (MSISDN)
Third field - The Mobile Country Code (MCC)
Fourth field - The Mobile Network Code (MNC)
Fifth field - The Country Name
Sixth field - The Network Name
Seventh Field - Whether the phone is recognised as live and switched on

TPS

To perform a TPS (with DNC) check use the above URL and specify TPS for the 'type' field.

The result returned for a TPS check will contain the following:

MSISDN = The mobile number checked (following normalisation)
TPS = Whether the MSISDN is seen on the TPS Register (Returning True if seen on the TPS, False if not)
CTPS = Whether the MSISDN is seen on the Corporate TPS Register (Returning True if seen on the Corporate TPS, False if not)
DNC = Whether the MSISDN is seen on our internal 'Do Not Call' list (Returning True if seen on the DNC, False if not)
TPSID = This is a unique reference for the TPS check, that can be quoted to us in the event of a query

The values returned will be in either JSON, XML or delimited formats depending on the original request using the "output" parameter.

JSON OUTPUT:

When using the TPS check type with JSON data format the following is returned

Sample URL:

https://api.datasoap.co.uk/?msisdn={MSISDN}&account={account}&password={password}&type=TPS&output=json

Sample Response:

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

XML OUTPUT:

When using the TPS check type with XML data format the following is returned

Sample URL:

https://api.datasoap.co.uk/?msisdn={MSISDN}&account={account}&password={password}&type=TPS&output=xml

Sample Response:

<DatasoapAPIResponse 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <TPSResult>
        <MSISDN>
             00447976123456
        </MSISDN>
        <TPS>
             True
        </TPS>
        <CTPS>
             False
        </CTPS>
        <DNC>
             True
        </DNC>
        <TPSID>
             12032505
        </TPSID>
    </TPSResult>
</DatasoapAPIResponse>

DELIMITED OUTPUT:

When using the TPS check type with comma delimited data format the following is returned

https://api.datasoap.co.uk/?msisdn={MSISDN}&account={account}&password={password}&type=TPS

Sample Response:

LQ|00447976123456|1|12032505|TPS|1|DNC|0|CTPS

First field - LQ - This is our prefix and can be ignored
Second field - The MSISDN we checked (after normalisation)
Third field - Whether the number is seen on the TPS (1 if seen on the TPS, else 0)
Fourth field - This is a unique ID for referencing the TPS lookup, and can be quoted to us in the event of a query
Fifth field - This field is used to indicate that the lookup of the previous field is of type TPS
Sixth field - Whether the number is seen on our internal Do Not Call (DNC) list (1 if seen on the DNC, else 0)
Seventh field - This suffix is used to indicate that the lookup of the previous field is of type DNC
Eighth field - Whether the number is seen on the Corporate TPS (1 if seen on the TPS, else 0)
Ninth field - This suffix is used to indicate that the lookup of the previous field is of type Corporate TPS

Landline

To perform a Landline number check use the above URL and specify 'landline' for the 'type' field.

The result returned for a Landline number check will contain the following:

Number = The landline number checked (following normalisation)
IsActive = Whether the landline number is active (Returning True if active, False if not)

The values returned will be in either JSON, XML or delimited formats depending on the original request using the "output" parameter.

JSON OUTPUT:

When using the landline check type with JSON data format the following is returned

Sample URL:

https://api.datasoap.co.uk/?number={number}&account={account}&password={password}&type=landline&output=json

Sample Response:

{
  "DatasoapAPIResponse": {
    "LandlineLookupResult": {
      "Number": "00441134960000",
      "IsActive": true
    }
  }
}

XML OUTPUT:

When using the landline check type with XML data format the following is returned

Sample URL:

https://api.datasoap.co.uk/?number={number}&account={account}&password={password}&type=landline&output=xml

Sample Response:

<DatasoapAPIResponse 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <LandlineLookupResult>
        <Number>
             00441134960000
        </Number>
        <IsActive>
             True
        </IsActive>
    </LandlineLookupResult>
</DatasoapAPIResponse>

DELIMITED OUTPUT:

When using the landline check type with the delimited data format the following is returned

https://api.datasoap.co.uk/?number={number}&account={account}&password={password}&type=landline

Sample Response:

LQ|00441502562267|1|

First field - LQ - This is our prefix and can be ignored
Second field - The landline number we checked (after normalisation)
Third field - Whether the number is active (1 if active, else 0)

Email Validation

This is a service provided to make it easy to integrate email verification within your application in real-time to ensure it is both syntactically correct and has a high rate of deliverability

Example Email Validation URL:

https://api.datasoap.co.uk/?account={account}&password={password}&validationemail={email to validate}

Account = Your account address username (email address)
Password = Your account password
Email - The email address which you wish to test in real-time for validity

Sample Response:

{
  "DatasoapAPIResponse": {
    "EmailValidationResult": {
      "Email": "steve@example.com",
      "User": "steve",
      "Domain": "example.com",
      "IsHighQuality": true,
      "Reason": "Accepted Email",
      "IsFree": true,
      "IsDisposable": false,
      "IsRole": false,
      "AcceptsAll": false
    }
  }
}

A successful email query will result in a response from the API with the following information

Email = The email address which we have tested for validity
User = The user portion of the email address
Domain = The domain portion of the email address
IsHighQuality = Determines the quality of this email address

If true then this field indicates a very high probability of an email to this address being delivered succesfully.

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.

Reason = This field provides a textual description of the reason for the result. Please see the table below for more information

Reason Description
Accepted Email The SMTP server has accepted this email address
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
Low Deliverability Deliverability cannot be guaranteed for this email address

IsFree = If true then the email belongs to a free email service such as Gmail or Yahoo! Mail
IsDisposable = If true then the email belongs to a disposable email service such as trashmail.com or mailinator.com. The email address is likely to have expired or will expire shortly.
IsRole = If set to true then this email address is associated with a function (postmaster, support, admin, etc) instead of a person.


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 at the bottom of this document

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

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 in your account for this operation. Please top-up using the website or by contacting your Account Manager
-97 * Temporary "Please report to Liquid11" usually occurs 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 rcognised as valid. Please ensure that the right lookup type is selected (e.g, HLR is only for mobile numbers) and that the value is syntactically corrct

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

Print this page