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.

Authentication

Set up an API token under Profile → API Authentication - the same token the Validation API uses. Make sure to use the right token for the use case, and never expose a private token to an end user. Make sure you have credits for the services you want to run; if not, purchase them from the bundles page.

All requests go to api.datasoap.co.uk over SSL (port 443).

Authorization: Bearer f07772e880ae4789b5a964c91a151a...

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.

Status is one of Processing, Failed or Complete. Note that this endpoint reports a finished job as Complete while /v1/batch/jobs reports the same job as Finished - match on both if you read from each of them.

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