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

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

Example Request

URL:

https://api2.datasoap.co.uk

Headers:

Authorization: Basic dXNlckBNb2JpbGVWZXJpZmljYXRpb24uY29tOkFwIVQzc3QxMjM=

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