Synchronous API

The Data Soap synchronous API allows clients to perform individual lookups using our data validation service.
This guide is made available to provide the necessary technical information to integrate
Data Soaps services into our client's bespoke systems.

Looking for something else?

Asynchronous API or Batch API

Synchronous API


Currently the synchronous API supports the following validation checks.

  • HLR (Home Location Register)
  • Landline
  • TPS (Telephone Preference Service)
  • Unsubscribe
  • Email
  • MPS (Mailing Preference Service)

How it works

Foremost the API is synchronous, that means once a request is sent no data will be returned back until the request is finished.

Simply put, a HTTP request is made by the client server to the API and once the validation is complete the result is returned directly back. Meanwhile the server has to wait for the response.


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
  • Because of the nature of some of the lookup types namely HLR, some submissions may result in a heavily delayed response. However, a correctly formatted lookup usually returns a result in less than a second in the majority of cases.

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 the 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 using SSL on port 443, The account credentials and lookup details need to be appended as a query string. The API will always return a 200 (OK) response.

URL

https://api.datasoap.co.uk/?output=json&number={Number}&type={Type}&validationEmail={Email}&validationAddress={Address}&validationName={Name}

Headers:

Authorization: Token {Token}

URL Parameters

Name

Optional?

Description

Examples

Output

No

The output format, keep this as JSON (Our recommend format)

JSON

Account

No

The account owners current email address

joe.b@datasoap.com

Password

No

Current password for the account

#101#DataSoap

Type

No

The type of lookup

HLR, Landline, TPS, Unsubscribe, Email, MPS

Number

Yes

Phone number to lookup

0207 856 0422

ValidationEmail

Yes

Email address to lookup

joe.b@datasoap.co.uk

ValidationAddress

Yes

Postal address to lookup

61 Alexandra Road, Lowestoft, Suffolk, NR32 3LQ.

ValidationName

Yes

Name to lookup

Joe Bloggs

Note: The output format should be kept as JSON, as this is our supported and recommended format. We also support XML, however this documentation is geared towards JSON.


HTTP Responses

Each lookup type has its own response model and as such our response format has a 2 tier JSON container format which indicates the type of response. The first tier 'DataSoapAPIResponse' indicates a response from our API and the second tier is for the type of lookup result e.g.

                {
"DataSoapAPIResponse": {
"HlrLookupResult": {
}
}
}

In the event of an error the response will have a field 'ErrorCode' which is a numeric representation of a specific error that needs to be handled by the requestor. It is important that the ErrorCode is handled correctly. Error responses will look like the following:

    {
"DataSoapAPIResponse": {
"HlrLookupResult": {
"ErrorCode": -96
}
}
}

HTTP Response Details

Generic 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 on your account for this operation. Please top-up using the website or by contacting your Account Manager

-97

* Temporary

"Please report to Liquid11" is usually seen 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 recognised as valid. Please ensure that the right lookup type is selected (e.g, HLR (Mobile Validation) is only for mobile numbers) and that the value is syntactically correct

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

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

Test the API