Batch API

Introduction

The Batch API is a synchronous API with multiple endpoints tied directly to Data Soap's backend batch system. Upload a list of lookups in JSON format and you'll get back a unique job ID, which you then use to check status and retrieve results.

Considerations

• Treat your account details and credentials as secret - you are responsible for every request submitted.
• Every submission to the system is audited for management and security purposes.
• Submitting duplicate lookups bills your account for each individual submission.

Getting started

Set up an API password from your account's profile section - by default, API access is denied until a password is set. Make sure you have credits for the services you want to run; if not, purchase them from the bundles page.

All requests go to api2.datasoap.co.uk over SSL (port 443). The endpoint only supports POST requests. Credentials are passed via HTTP Basic Auth - email and password delimited with a colon.

Authorization: Basic user@datasoap.com:Ap!T3st123

Base64-encoded credentials are also accepted:

Authorization: Basic dXNlckBNb2JpbGVWZXJpZmljYXRpb24uY29tOkFwIVQzc3QxMjM=

Start a batch

Start a new batch of lookups. Provide the list of lookups and the request type (e.g. TPS, HLR) - this is the first step in the process.

{
  "Lookups": ["07916872100"],
  "Type": "tps",
  "Name": "batch api test"
}

{ "JobId": 18930 }

Keep hold of the returned JobId - you'll need it for every request after this one.

Get a job

Gets the result of a job, or its current status if it isn't finished yet. While pending or processing, a progress field shows the current state; once finished, a results field lists each lookup with its result.

{
  "JobId": 18930,
  "Name": "batch api test",
  "Type": "Tps",
  "Status": "Processing",
  "Progress": { "Progress": 42.71, "State": "Performing TPS" },
  "Started": "2018-10-18T14:32:07.057"
}

{
  "JobId": 18930,
  "Name": "batch api test",
  "Type": "Tps",
  "Status": "Complete",
  "Results": [{ "Lookup": "07916872100", "Result": { "Msisdn": "0447916872100", "Tps": true, "Ctps": false, "Dnc": false } }],
  "Started": "2018-10-18T10:25:40.747",
  "Finished": "2018-10-18T10:25:41.34"
}

{
  "JobId": 18930,
  "Name": "batch api test",
  "Type": "Hlr",
  "Status": "Complete",
  "Results": [{ "Lookup": "07916872100", "Result": { "Msisdn": "0447916872100", "Mcc": 234, "Mnc": "30", "CountryName": "United Kingdom of Great Britain and Northern Ireland", "NetworkName": "UK - Everything Everywhere Limited (TM)", "On": true } }],
  "Started": "2018-10-18T10:25:40.747",
  "Finished": "2018-10-18T10:25:41.34"
}

{
  "JobId": 18930,
  "Name": "batch api test",
  "Type": "Landline",
  "Status": "Complete",
  "Results": [{ "Lookup": "07916872100", "Result": { "IsActive": true, "Msisdn": "0447916872100" } }],
  "Started": "2018-10-18T10:25:40.747",
  "Finished": "2018-10-18T10:25:41.34"
}