Asynchronous Job Tutorial

Overview

The Asynchronous Solutions all require the use of an Asynchronous Job as the container for the larger Asynchronous process. Before using any of the Asynchronous Solutions, you must first have an Asynchronous Job to use.

The Asynchronous Job Solutions include Creating an Asynchronous Job and Retrieving an Asynchronous Job.

Create Asynchronous Job URI

The Create Asynchronous Job URI accepts the name of a new Asynchronous Job and returns a uniquely generated Asynchronous Job Id. You will need this Asynchronous Job Id in future Asynchronous Solutions.

Required Information

The Create Asynchronous Job URI requires you to have an Authorization Token. If you have not retrieved an Authorization Token yet, follow the Authorization Tutorial before continuing.

The Create Asynchronous Job URI, li ke all of the solution URIs, also requires you to have an API Key. If you do not know your API Key, contact support to retrieve it. The API Key should be provided in the request header with the header attribute: x-api-key

The Create Asynchronous Job URI must be used with a POST request, where the request payload contains the Name of the Job. The Name of the Job is entirely for your reference.

Optional Information

The request payload can also contain several optional attributes. The Output Format is used to specify what format you would like your output files in. The API currently only supports JSON. If this attribute is not specified in the request payload, JSON is used as the default.

The Notification URL is used when you want to receive an automatic message when the Job finishes. This URL should use the https protocol, and should refer to URL which you are capable of using for listening for Job state updates. If the Notification URL has been provided in the request payload, you must also provide the Notification Method. The API currently only supports GET and POST http methods. The Notification Method tells the API what method to use when sending a Job state update to your Notification URL. To read more about Notifications, view the Using Notification URLs and Notification Methods section of the User Guide.

Example

Request URL

The URL for the Create Asynchronous Job URI is: https://api.thedatagroup.com/{version}/async/append/email/job, where {version} is the API Version you wish to use.

Request Headers

Request Payload

The request payload for the Create Asynchronous Job URI must contain the name attribute. You can include the output_format, notification_URL, and notification_method attributes if you’d like.

{ "name": "Tutorial Job", "output_format": "JSON", "notification_URL": "https://www.example.com/api/job-listener", "notification_method": "POST" }

cURL Example

To query the Create Asynchronous Job URI, you can use one of the provided SDKs, a REST Client, or a simple cURL command. Below is an example of the cURL command for the example input information.

curl -X POST -H "Content-Type: application/json" -H "AuthorizationToken: {your_token}" -H "x-api-key: {your_key}" -H "Cache-Control: no-cache" -d '{ "name": "Tutorial Job", "output_format": "JSON", "notification_URL": "https://www.example.com/api/job-listener", "notification_method": "POST" }' "https:// api.thedatagroup.com/v3/async/append/email/job"

Response Payload

The response payload for the Create Asynchronous Job URI will contain the generated Job Id.

{ "job_id": "160718103247ad0" }

Retrieve Asynchronous Job URI

The Retrieve Asynchronous Job URI is a GET request which can be used to retrieve the current information regarding the Job. Contained in the response payload is the current Job State, the states of all of the Asynchronous Batch and Asynchronous Batch-Files within the Job, and the list of the ids of all of the Asynchronous Batch and Asynchronous Batch-Files within the Job.

Required Information

The Retrieve Asynchronous Job URI requires you to have an Authorization Token and the Job Id for the Job you wish to retrieve. If you have not retrieved an Authorization Token yet, follow the Authorization Tutorial before continuing.

The Retrieve Asynchronous Job URI, like all of the solution URIs, also requires you to have an API Key. If you do not know your API Key, contact support to retrieve it. The API Key should be provided in the request header with the header attribute: x-api-key The Retrieve Asynchronous Job URI must be used with a GET request, where the Job Id is provided in the URI path.

Example

Request URL

The URL for the Retrieve Asynchronous Job URI is: https://api.thedatagroup.com/{version}/async/append/email/job/{job_id}, where {version} is the API Version you wish to use and {job_id} is the Id of the Job you wish to retrieve.

Request Headers

cURL Example

To query the Retrieve Asynchronous Job URI, you can use one of the provided SDKs, a REST Client, or a simple cURL command. Below is an example of the cURL command using the Job Id: 160718103247ad0.

curl -X GET -H ""Content-Type: application/json" -H "AuthorizationToken: {your_token}" -H "x-api-key: {your_key}" -H "Cache-Control: no-cache"  "https://api.thedatagroup.com/v3/async/append/email/job/160718103247ad0"

Response Payload

{ "state": "COMPLETED", "number_batches_waiting_for_upload": 0, "number_batches_queued": 0, "number_batches_in_progress": 0, "number_batches_completed": 5, "number_batches_failed": 0, "number_batches_malformed": 0, "created_date": "1461726337744", "output_format": "JSON", "batch_list": [ "54115674feaf