Batches

Batches Overview

The batches API allows you to perform bulk operations on various resources such as contacts, groups, shipments, and trackers. This can streamline processes like updating large datasets, removing obsolete entries, and more.

# Batches Actions

• merge: Updates and/or creates the items in the batch.
• overwrite: Creates and/or updates items in the batch, and deletes all other items.
• delete: Deletes all the items in the batch. A valid id is required for each item.

# Batches Resources

Currently, the following resources are supported:

• contact: All actions applicable.
• group: All actions applicable.
• shipment: Only merge action is applicable.
• tracker: Only merge action is applicable.
• asset: Only merge action is applicable

# Batches Phases

Each batch can have 4 phases:

• parsing: Parses the JSON payload/CSV file and removes all duplicates.
• validation: Removes rows/items with invalid ids.
• processing: Calls the underlying controllers in batches to write or delete items.
• cleanup: Only applicable for the action overwrite. Removes all resources not found in the batch.

# Batches Modes

• sync: All phases are synchronous. The batch is immediately processed with some restrictions.
• mixed: parsing and validation phases are synchronous; processing and cleanup are asynchronous. This is the default mode.

# Batches Statuses

# Initial/Intermediate Statuses

• queued: Batch is valid and is in queue to be processed.
• processing: Writes/deletes/overwrites are being processed.

# Final Statuses

• completed: Processing complete.
• failed: Unable to start or complete processing.
• timed_out: Batch took too long to process.

# Stats

• How many resources were created, updated, and/or deleted in this batch.
• For the overwrite action, the number of resources removed as overwritten.

# Other Properties

• reason: Reason for a final status other than completed.
• has_upload_file: Indicates if the original payload can be downloaded.
• has_errors_file: Indicates if error rows/items can be downloaded.
• _upload_url: URL for uploading a file/payload via a signed URL.
• _upload_csv_url: URL to download the original payload as a CSV file.
• _upload_json_url: URL to download the original payload as a JSON file.
• _errors_csv_url: URL to download errors as a CSV file.
• _errors_json_url: URL to download errors as a JSON file.