Asynchronous API

Introduction

The asynchronous API currently supports TPS, HLR, Landline and Unsubscribe lookups (more coming soon). Instead of waiting for a result, you get a receipt with a job reference immediately - once the background job completes, Data Soap makes a request to a webhook URL you provide, with the result.

Considerations

• No restriction on parallel submissions, though a throttling limit may apply to an IP address under heavy traffic.
• Treat account details and credentials as confidential - you're responsible for every request submitted.
• Every submission is audited for management and security purposes.
• Duplicate lookups are billed individually.

Looking for something else? See the Synchronous API or the Batch API.

Authentication

Set up an API password from your account's profile section - by default API access is denied until a password is set. Send a token with each request in the auth header; you can create tokens from the Profile section once logged in. There are two kinds:

• Private - for backend systems where the token stays invisible to users, e.g. our C#, Python and PHP SDKs.
• Public - for front-end validation scripts such as JavaScript, using our JS SDK.

Tokens are unique to your account - create as many as you want, and assign rate limits to safeguard against excessive use.

Making a request

All requests go to https://api.datasoap.co.uk/v1/async over SSL (port 443) - POST only.

Authorization: Token 29291c3daf4547f596cfd1ef2c8f664d0f726318b3084c1da1cbe05ffaad1bd5=

{
  "Lookup": "00447976123456",
  "Type": "TPS",
  "PostbackUrl": "http://webhook.yourdomain.com"
}

{ "Job": "56effe97-8f3a-4636-9dd0-78bc1faee005" }

Receiving responses

You need a publicly accessible webhook ready to receive HTTP POST requests in JSON. The response has an outer layer confirming the job details, and an inner Result layer whose shape depends on the lookup type.

{
  "Type": "TPS",
  "Job": "56effe97-8f3a-4636-9dd0-78bc1faee005",
  "Result": {}
}

An error surfaces as ErrorCode and ErrorMessage - on the initial request for account/data issues, or via the webhook for lookup-specific issues.

{ "ErrorCode": -98, "ErrorMessage": "NoCredit" }

TPS

{
  "Type": "TPS",
  "Job": "56effe97-8f3a-4636-9dd0-78bc1faee005",
  "Result": { "MSISDN": "00447976123456", "Tps": true, "Ctps": false, "Dnc": false, "TpsId": 782452 }
}

HLR

{
  "Type": "HLR",
  "Job": "ed5bdff8-1c6d-4d17-a5f2-33a9cbf27d90",
  "Result": { "MSISDN": "00447976123456", "MCC": "234", "MNC": "10", "CountryName": "United Kingdom of Great Britain and Northern Ireland", "NetworkName": "UK - 02 (UK) Limited", "On": true }
}

Landline

{
  "Type": "Landline",
  "Job": "56effe97-8f3a-4636-9dd0-78bc1faee005",
  "Result": { "Number": "00441134960000", "IsActive": true }
}

Unsubscribe

{
  "Type": "Unsubscribe",
  "Job": "76effe97-833a-4636-9dd0-73bc10afe035",
  "Result": { "MSISDN": "00442078560422", "OnCompany": false, "OnCompanyDateAdded": null }
}