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 our synchronous API?

Asynchronous API


Currently the asynchronous API supports the following validation checks.

  • TPS (Telephone Preference Service)
  • HLR (Home Location Register)
  • Landline
  • Unsubscribe
  • (More coming soon)

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 api2.datasoap.co.uk 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://api2.datasoap.co.uk

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

Error Codes

Current error codes returned by the platform are:

Code Applies to T or P Description
-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 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 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.

Test the API