Asynchronous Batch-File Tutorial
Overview
An Asynchronous Batch-File is one of the two methods of sending records to the API, with the other being an Asynchronous Batch. The Asynchronous Batch-File, unlike the Asynchronous Batch, requires a file upload to send the records to the API. The Asynchronous Batch-File has a data limit of 50 MB. If your data is smaller than 10 MB, you should consider using the Asynchronous Batch-File instead. If your data is larger than 50 MB, you will need to divide your data into several Batch-Files.
The Asynchronous Batch-File Solutions include Creating an Asynchronous Batch-File, Retrieving the State of an Asynchronous Batch-File, and Retrieving the Results of an Asynchronous Batch-File after it has finished being processed.
Create Asynchronous Batch-File URI
The Create Asynchronous Batch-File URI accepts some optional attributes and returns a uniquely generated Asynchronous Batch-File Id and an Upload URL. This Asynchronous Batch-File Id can be used later to check on the state of your Batch-File as well as to retrieve the results for your Batch-File. You will use the provided Upload URL to upload your records to the API, using an http PUT request. This URL will expire after 8 hours.
Required Information
The Create Asynchronous Batch-File 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-File 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-File URI must be used with a POST request. There are no required attributes in the request payload.
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 Batch-File finishes. This URL should use the https protocol, and should refer to URL which you are capable of using for listening for Batch-File 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-File 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-File URI is: https://api.thedatagroup.com/{version}/async/append/email/job/{job_id}/batch-file, where {version} is the API Version you wish to use and {job_id} is the Id of the Job you are creating the Batch-File under.
Request Headers
Header Attribute Header Value x-api-key {your api key} AuthorizationToken {your authorization token} Content-Type application/json
| 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-File URI does not have any mandatory attributes. However, you can include the output_format, notification_URL, and notification_method attributes if you’d like.
{
"output_format": "JSON",
"notification_URL": "https://www.example.com/api/batch-file-listener",
"notification_method": "POST"
}cURL Example
To query the Create Asynchronous Batch-File 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 '{
"output_format": "JSON",
"notification_URL": "https://www.example.com/api/batch-file-listener",
"notification_method": "POST"
} ' "https://api.thedatagroup.com/v3/async/append/email/job/160718103247ad0/batch-file"Response Payload
The response payload for the Create Asynchronous Batch-File URI will contain the generated Batch-File Id and Upload URL for the created Batch-File.
{
"batch_id": "160427130036tew",
"upload_URL": "https://s3.amazonaws.com/..."
}Retrieve Asynchronous Batch-File URI
The Retrieve Asynchronous Batch-File URI is a GET request which can be used to retrieve the current state of the Batch-File. Contained in the response payload is the current Batch-File State and the Batch-File’s creation date.
Required Information
The Retrieve Asynchronous Batch-File 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-File Id and the Asynchronous Job Id associated with the Batch-File.
The Retrieve Asynchronous Batch-File 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-File URI must be used with a GET request, where the Job Id and the Batch-File Id are provided in the URI path.
Example
Request URL
The URL for the Retrieve Asynchronous Batch-File URI is: https://api.thedatagroup.com/{version}/async/append/email/ job/{job_id}/batch-file/{batch_id}, where {version} is the API Version you wish to use, {job_id} is the Id of the Job associated with the Batch-File you wish to retrieve, and {batch_id} is the Id of the Batch-File you wish to retrieve.
Request Headers
Header Attribute Header Value x-api-key {your api key} AuthorizationToken {your authorization token} Content-Type application/json
| 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-File 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-File 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-file/160427130036tew"Response Payload
The response payload for the Retrieve Asynchronous Batch-File URI will contain the requested Batch-File’s current state and the Batch-File’s creation date.
{
"state": "COMPLETED",
"created_date": "1461726337744"
}Retrieve Asynchronous Batch-File Result URI
The Retrieve Asynchronous Batch-File Result URI is a GET request which can be used to retrieve the result of the processed records in the Asynchronous Batch-File. This URI can only be used once the Asynchronous Batch-File State has been set to: COMPLETED. Contained in the response payload is a download URL which can be used to retrieve the processed Batch-File, using an http GET request.
Required Information
The Retrieve Asynchronous Batch-File 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-File Id and the Asynchronous Job Id associated with the Batch-File.
The Retrieve Asynchronous Batch-File 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-File Result URI must be used with a GET request, where the Job Id and the Batch-File Id are provided in the URI path. Example Request URL The URL for the Retrieve Asynchronous Batch-File Result URI is: https://api.thedatagroup.com/{version}/async/append/email/job/{job_id}/batch-file/{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-File you wish to retrieve, and {batch_id} is the Id of the Batch-File you wish to retrieve.
Request Headers
Header Attribute Header Value x-api-key {your api key} AuthorizationToken {your authorization token} Content-Type application/json
| 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-File 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-File 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-file/160427130036tew/result"Response Payload
The response payload for the Retrieve Asynchronous Batch-File Result URI will contain the requested Batch-File’s download URL, which can be used to download the processed Batch-File.
{
"download_url": "https://s3.amazonaws.com/..."
} 