Batches

Retrieve Batches

This allows you to retrieve details of a specific batch or list multiple batches.

# Retrieve Batch

Retrieve a single batch using its id.

        const response = await fetch("https://api.packagex.io/v1/batches/batch_123", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
  },
});
const batch = await response.json();

      

# Retrieve Batch Files

The following 'boolean' query parameters are available in the GET /v1/batches/:batch_id API to download the relevant associated files for the batch. Please note that upload and result files are only available if respective properties (save_upload, save_result) were set when creating the batch.

• include_upload_csv
• include_upload_json
• include_errors_csv
• include_errors_json
• include_result_json

Please note that presigned URLs are returned for each of these respectively (if passed) to download the file. They are present on the Batch object as the following properties:

• _upload_csv_url
• _upload_json_url
• _errors_csv_url
• _errors_json_url
• _result_json_url

# List Batches

# Example

When you want to retrieve multiple batches, your data property on the result will always be an array even if you don't have any batches. The batches are returned in chronological order by creation date.

        const response = await fetch("https://api.packagex.io/v1/batches", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const batches = response.data;
const pagination = response.pagination;

      

# Pagination

If the has_more property on the pagination object is set to true, you know there are more batches in the database that have not been returned to you. The pagination object also has a page property indicating your current offset and a limit property. The total_count property in pagination returns the total number of batches in the database.

By default, the page is set to 1 and the limit is 25.

If we want to query for batches 26 - 50, we would request page 2 with a query parameter.

        const response = await fetch("https://api.packagex.io/v1/batches?page=2&limit=25", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const batches = response.data; // the array of batches 25 - 50
const pagination = response.pagination; // the pagination object

      

# Filter

You can filter batches by resource, mode, via, and status properties.

• resource - Filter by the type of resource in the batch. Available resources are: contact, group, shipment, and tracker.
• mode - Filter by the mode of the batch. Available modes are: sync, mixed.
• via - Filter by the method of batch creation. Available options are: api, file.
• status - Filter by the status of the batch. Available statuses are: requested, queued, processing, completed, failed, timed_out, expired.

        const response = await fetch("https://api.packagex.io/v1/batches?resource=contact&mode=mixed", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const batches = response.data; // the array of batches
const pagination = response.pagination; // the pagination object