Batch API

How it works

The Batch API is a synchronous API with multiple end points which directly ties to DataSoaps backend batch system, a list of lookups can be uploaded in Json format and a unique identifier is given which can then be used to check the status of the batch job and subsequently get the results.

Considerations

Prior to integrating with this Data Soap API, the following should be considered:

Your account details and credentials should be treated as secret because you are responsible for each 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="

Endpoints

Batch [POST]

Start a new batch of lookups through the batch system. This is the first step in the process you provide a list of lookups and the request type i.e. TPS, HLR, etc.

URL

https://api2.datasoap.co.uk/v1/batch

Request example:

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

Response

{
    "JobId": 18930
}

Note: The JobId in the response is needed for further requests, make sure you keep hold of it.

Job/{JobId} [GET]

Get the result of a job, this will also display the current status of the job if the job is not complete.

https://api2.datasoap.co.uk/v1/batch

Note: The response changes based on the status while pending / processing a field will be present in the request that shows the current process and state of the job, once the jobs is finished a results field will be present with each lookup and the corresponding lookup result.

Response Example (Pending):

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

Response Example (TPS):

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

Response Example (HLR):

{
    "JobId": 18930,
    "Name": "batch api test",
    "Type": "Tps",
    "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"
}

Response Example (HLR):

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

Response Example (Landline):

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

Jobs [GET]

Gets a list of all recent api jobs either processed or processing, this can be helpful the JobId somehow gets lost for a api job or as overview of the jobs.

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

URL

https://api2.datasoap.co.uk/v1/batch/jobs

Response Example (Pending):

[
    {
        "JobId": 31105,
        "Name": "batch api test",
        "Type": "Landline",
        "Status": "Finished",
        "Finished": "2018-10-18T14:36:29.637",
        "Progress": {
            "Progress": 0,
            "State": "Pending"
        },
        "Started": "2018-10-18T14:36:29.013"
    },
    {
        "JobId": 31104,
        "Name": "batch api test2",
        "Type": "Hlr",
        "Status": "Finished",
        "Finished": "2018-10-18T14:35:00.15",
        "Progress": {
            "Progress": 100,
            "State": "Finished"
        },
        "Started": "2018-10-18T14:34:59.153"
    }
]

Batch API

Looking for something else?

Batch API

Request example:

Response