Asynchronous API

Currently the asynchronous API supports the following validation checks.

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

How it works

The API is asynchronous, which means instead of waiting for the result of a validation check (meanwhile locking up the web client) an endpoint for the result is provided as part of the request. After each request the web client gets a receipt with an indicator of the background job. Once the background job is completed a web request is made to the provided endpoint with the result.

Simply put an asynchronous request is a form of two-way communication where the requestor does not have to wait around for the result.

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

API

Getting Started

The first step is to setup an API password which can be set from your accounts profile section, By default access to 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/v1/async using SSL on port 443, The endpoint only supports POST requests.

Authentication

You will need to send a token with each request in the authentication header, you can assign tokens from under the Profile section whilst logged in to the website. There are two kinds of tokens:

Private: which can be used for backend systems where the token will not be visible to users. i.e. Api’s, Datasoaps C#, Python and PHP SDKs
Public: for use in front end validation scripts such as JavaScript using our Javascript SDK

These tokens are unique to your datasoap account and you can create as many as you want, you can also assign rate limits that will safe guard your account from excessive use.

Example Request

URL:

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

Headers:

Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=

Body:

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

Response (Receipt):

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

Body Parameters

Name	Optional?	Description	Examples
Type	No	The type of lookup	HLR, Landline, TPS, Unsubscribe
Lookup	No	The validation lookup e.g. phone number	0207 856 0422
PostbackUrl	No	The URL to send the lookup result too.	http://webhook.yourdomain.com

Receiving responses

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.

    {
   "Type": "TPS",
   "Job": "56effe97-8f3a-4636-9dd0-78bc1faee005",
   "Result": {
   }
}

In the event of an error the response will have two fields ‘ErrorCode’ and ‘ErrorMessage’ which provides both a numeric representation of specific error and a textual version. Errors can be returned on both the initial http request and the response via the webhook, 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.

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

Response Details

TPS

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

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 bis registered with the Corporate Telephone Preference Service.
DNC	Whether the phone number is on our internal Do Not Call list.

Sample Response:

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

HLR

The result of a successful HLR lookup with contain the following fields inside the Result field:

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 Response:

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

Landline

The result of a successful Landline lookup with contain the following fields inside the Result field:

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

Sample Response:

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

Unsubscribe

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

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 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 Response:

    
    {"Type":"Unsubscribe", "Job": "76effe97-833a-4636-9dd0-73bc10afe035" ,"Result": { "MSISDN": "00442078560422", "OnCompany": false, "OnCompanyDateAdded": null } }

Error Codes

Current error codes returned by the platform are:

Code	Applies to	T or P
-98	Permanent	You do not have enough credit in your account for this operation. Please top-up using the website or by contacting your Account Manager
-96	Permanent	The number wasn’t recognised as a valid UK mobile number. This could be a number formatted incorrectly with bad characters or from a range that’s not been allocated for mobile use
-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.
-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 or -97	* 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

* Temporary error codes may return a different result when tried a second time in quick succession due to network fluctuations.

Asynchronous API

The Data Soap asynchronous API allows clients to perform individual lookups using our data validation service and retrieve the results later on. This guide is made available to provide the necessary technical information to integrate Data Soap’s API’s into bespoke systems.

Looking for something else?

Asynchronous API

Authentication

Example Request

Body Parameters

Sample Response:

Sample Response:

Sample Response:

Sample Response:

Api Test

HTTP Request

Authentication Header

Request Parameters

Request Body

Status

Response Body

Webhook