Asynchronous Batch Tutorial

Overview

An Asynchronous Batch is one of the two methods of sending records to the API, with the other being an Asynchronous Batch-File. The Asynchronous Batch, unlike the Asynchronous Batch-File, allows you to send the records to the API when the Asynchronous Batch is created. The Asynchronous Batch has a data limit of 10 MB. If your data is larger than 10 MB, you should use the Asynchronous Batch-File instead.

The Asynchronous Batch Solutions include Creating an Asynchronous Batch, Retrieving the State of an Asynchronous Batch, and Retrieving the Results of an Asynchronous Batch after it has finished being processed.

Create Asynchronous Batch URI

The Create Asynchronous Batch URI accepts a list of records and returns a uniquely generated Asynchronous Batch Id. This Asynchronous Batch Id can be used later to check on the state of your batch as well as to retrieve the results for your batch.

Required Information

The Create Asynchronous Batch URI requires you to have an Authorization Token. If you have not retrieved an Authorization Token yet, follow the Authorization Tutorial before continuing. It also requires you to have a valid Asynchronous Job Id. If you have not created a new Asynchronous Job yet, follow the Asynchronous Job Tutorial before continuing.

The Create Asynchronous Batch 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 Create Asynchronous Batch URI must be used with a POST request, where the request payload contains the list of records to have processed. For more information on how to correctly format your record data, view the Formatting The Record Data section of the User Guide.

Optional Information

The request payload can also contain several optional attributes. The Notification URL is used when you want to receive an automatic message when the Batch finishes. This URL should use the https protocol, and should refer to URL which you are capable of using for listening for Batch 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 Batch 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 Batch URI is: https://api.thedatagroup.com/{version}/async/append/email/job/{job_id}/batch, where {version} is the API Version you wish to use and {job_id} is the Id of the Job you are creating the Batch under.

Request Headers

Header Attribute	Header Value
x-api-key	{your api key}
AuthorizationToken	{your authorization token}
Content-Type	application/json

Request Payload

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

{
 "notification_URL": "https://www.example.com/api/batch-listener",
 "notification_method": "POST",
 "data": [
 {
 "external_id": "1",
 "first_name": "John",
 "last_name": "Smith",
 "address_1": "123 Fake Street",
 "city": "Springfield",
 "state": "OR",
 "zipcode": "90701"
 },
 {
 "external_id": "2",
 "first_name": "Jane",
 "last_name": "Smith",
 "address_1": "123 Fake Street",
 "city": "Springfield",
 "state": "OR",
 "zipcode": "90701"
 }
 ]
}

cURL Example

To query the Create Asynchronous Batch 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, using the Job Id: 160718103247ad0.

curl -X POST -H "Content-Type: application/json" -H "AuthorizationToken: {your_token}" -H "x-api-key: {your_key}" -H "Cache-Control: no-cache" -d '{
 "notification_URL": "https://www.example.com/api/batch-listener",
 "notification_method": "POST",
 "data": [
 {
 "external_id": "1",
 "first_name": "John",
 "last_name": "Smith",
 "address_1": "123 Fake Street",
 "city": "Springfield",
 "state": "OR",
 "zipcode": "90701"
 },
 {
 "external_id": "2",
 "first_name": "Jane",
 "last_name": "Smith",
 "address_1": "123 Fake Street",
 "city": "Springfield",
 "state": "OR",
 "zipcode": "90701"
 }
 ]
 } ' "https://api.thedatagroup.com/v3/async/append/email/job/160718103247ad0/batch "

Response Payload

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

{
 "batch_id": "160427130036tew"
}

Retrieve Asynchronous Batch URI

The Retrieve Asynchronous Batch URI is a GET request which can be used to retrieve the current state of the Batch. Contained in the response payload is the current Batch State and the Batch’s creation date.

Required Information

The Retrieve Asynchronous Batch URI requires you to have an Authorization Token. If you have not retrieved an Authorization Token yet, follow the Authorization Tutorial before continuing. It also requires you to have a valid Asynchronous Batch Id and the Asynchronous Job Id associated with the Batch.

The Retrieve Asynchronous Batch 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 Batch URI must be used with a GET request, where the Job Id and the Batch Id are provided in the URI path.

Example

Request URL

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

Request Headers

Header Attribute	Header Value
x-api-key	{your api key}
AuthorizationToken	{your authorization token}
Content-Type	application/json

cURL Example

To query the Retrieve Asynchronous Batch 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 and the Batch Id: 160427130036tew.

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/batch /160427130036tew"

Response Payload

The response payload for the Retrieve Asynchronous Batch URI will contain the requested Batch’s current state and the Batch’s creation date.

{
 "state": "COMPLETED",
 "created_date": "1461726337744"
}

Retrieve Asynchronous Batch Result URI

The Retrieve Asynchronous Batch Result URI is a GET request which can be used to retrieve the result of the processed records in the Asynchronous Batch. This URI can only be used once the Asynchronous Batch State has been set to: COMPLETED. Contained in the response payload is an array of processed records.

Required Information

The Retrieve Asynchronous Batch Result URI requires you to have an Authorization Token. If you have not retrieved an Authorization Token yet, follow the Authorization Tutorial before continuing. It also requires you to have a valid Asynchronous Batch Id and the Asynchronous Job Id associated with the Batch.

The Retrieve Asynchronous Batch Result 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 Batch Result URI must be used with a GET request, where the Job Id and the Batch Id are provided in the URI path.

Example

Request URL

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

Request Headers

Header Attribute	Header Value
x-api-key	{your api key}
AuthorizationToken	{your authorization token}
Content-Type	application/json

cURL Example

To query the Retrieve Asynchronous Batch Result 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 and the Batch Id: 160427130036tew.

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/batch/160427130036tew/result"

Response Payload

The response payload for the Retrieve Asynchronous Batch Result URI will contain the requested Batch’s result data record list.

{
 "data": [
 {
 "external_id": "1",
 "first_name": "John",
 "last_name": "Smith",
 "address_1": "123 Fake Street",
 "city": "Springfield",
 "state": "OR",
 "zipcode": "90701",
 "email": "john.smith@example.com"
 },
 {
 "external_id": "2",
 "first_name": "Jane",
 "last_name": "Smith",
 "address_1": "123 Fake Street",
 "city": "Springfield",
 "state": "OR",
 "zipcode": "90701",
 "email": "jane.smith@example.com"
 }
 ]
}