Async API Documentation - Data Cleaning

Introduction

The asynchronous version of the Data Soap API enables clients to submit single number lookups for HLR (Mobile Validation), TPS, Or Landline checking via HTTP post request, results are than provided via a postback to a web hook.

This guide provides technical information for developers to integrate 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:

• 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.
• The client should ensure that all account details are treated as confidential and are responsible for all requests submitted.
• All submissions to the system are audited for account management and security purposes.
• If you submit a mobile or landline phone number for checking multiple times then your account is billed for each, individual submission.
• Concerning HLR (Mobile Validation): 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.

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.

The credentials will need to be passed on each request using the authentication header using basic authorization, the email and password need to be delimitated with a colon i.e. "Authorization: Basic user@MobileVerification.com:Ap!T3st123". The api will also accept base64 encrypted credentials i.e. "Authorization: Basic dXNlckBNb2JpbGVWZXJpZmljYXRpb24uY29tOkFwIVQzc3QxMjM="

URL

Clients should make calls to https://api.datasoap.co.uk/v1/async 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.

Making a request

To perform a look up you need to generate a post body, ready to send to the api and ensure you have a webhook ready to receive the response.

Both the request and response will need to be formatted in JSON, the fields needed to perform a look up request are as follows:

Lookup = The lookup value i.e. mobile / landline number
Type = The type of lookup being performed. Currently supported types are (TPS, HLR (Mobile Validation), Landline)
PostbackUrl = The url the that the result response will be posted back to. The API will respond with a job id which you will need to record, once the request has been completed the result will be POSTed back to the url that you provided in the original request.

The api respond with a job id as a form of receipt and once the the request has been complete it will be posted back to the url provided.

Example request:

Sample request of performing a TPS lookup on 447976123456:

https://api.datasoap.co.uk/v1/async

Authorization: Basic dXNlckBNb2JpbGVWZXJpZmljYXRpb24uY29tOkFwIVQzc3QxMjM=

{
   "Lookup": "00447976123456",
   "Type": "TPS",
   "PostbackUrl": "http://webhook.yourdomain.com",
}

Response (Receipt)

{
   "Job": "56effe97-8f3a-4636-9dd0-78bc1faee005"
}

Receiving response

To receive a response, you must have a publicly accessible webhook ready to receive HTTP post requests in a JSON format.

The response object has two parts, an outer layer confirming the details sent in the request as well as job id. and an inner layer with the result of the of specific request, this inner results layer has different formats depending on the lookup type requested.

Example response:

{
   "Type": "TPS",
   "Job": "56effe97-8f3a-4636-9dd0-78bc1faee005",
   "Result": {
      "MSISDN": "00447976123456",
      "Tps": true,
      "Ctps": false,
      "Dnc": false,
      "TpsId": 782452,
   }
}

The fields contained within the individual response result depend on the lookup type performed and are as follows:

HLR (Mobile Validation) Result

The result returned for an HLR (Mobile Validation) 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

Example

{
   "Type": "HLR",
   "Job": "ed5bdff8-1c6d-4d17-a5f2-33a9cbf27d90",
   "Result": {
      "MSISDN": "00447976123456",
      "MCC": "234",
      "MNC": "10",
      "CountryName": "United Kingdom of Great Britain and Northern Ireland",
      "NetworkName": "UK - 02 (UK) Limited",
      "On": true
   }
}

TPS Result

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 the industry maintained Liquid11 '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

Example

{
   "Type": "TPS",
   "Job": "56effe97-8f3a-4636-9dd0-78bc1faee005",
   "Result": {
      "MSISDN": "00447976123456",
      "Tps": true,
      "Ctps": false,
      "Dnc": false,
      "TpsId": 782452,
   }
}

Landline Result

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)

Example

{
   "Type": "Landline",
   "Job": "56effe97-8f3a-4636-9dd0-78bc1faee005",
   "Result": {
      "Number": "00441134960000",
      "IsActive": true
   }
}

Error Codes

Errors can be returned on both the request and the response, however errors returned on the request are generally account or data validation issues, where errors on the results indicate issues with the specific look up.

Error response example

{
  "ErrorCode": -98,
  "ErrorMessage": "NoCredit"
}

Current error codes returned by the platform are:

* Temporary error codes may return a different result when tried a second time in quick succession due to network fluctuations. Permanent codes require a change to the recipient or network status of a mobile telephone number.

Print this page