Batches
Create & Update Batches
Create Batch(s)
This API will allow you to create a batch for performing bulk operations on resources such as contacts, groups, shipments, and trackers. The operations can be done using a traditional REST approach or by uploading a csv or excel file encoded as a base64 data URL or a public web URL.
Create Contacts
To create contacts through batches, the data array must contain objects of Contact Request Body.
For creating or updating contacts with common properties we can use properties
property of batch properties
is a map of properties that provide default values to the data array. If these properties are not defined for an item, the values in properties
object are used.
set
keyword will remove the contact from ALL previously associated groups and assigns them ONLY to the groups specified in this array. Each string in the array must be a unique group ID (e.g., "grp_1mcqP7TwkiSUybCWHcBMVb")
Here both contacts will be updated with different phone numbers but their groups will be set to the same group and both contacts will be added to the same locations.
Create Group
A group will let you nest other contacts in the group. You'll need to add a name and update the type for the contact to "group."
Create Shipment
Only the merge action is applicable for shipments. The shipment requires a tracking_number.
Create Tracker
Only the merge action is applicable for trackers. The tracker requires a tracking_number.
Use CSV
You can also create or update multiple resources using a CSV file. The following headers are required for the CSV file for contacts:
- Name - The name of the contact. If you have the name split by First Name and Last Name, you can pass that in instead.
Example CSV
We've already encoded this table into a base64 data URL to make it easier to test.
To create the contacts, you'll add the csv_url. If you want this to clear all of your existing contacts, you can also pass an overwrite
property set to true.
If you overwrite contacts, they will be all deleted. It's best to use this if you're syncing a list that has all of the contacts you want to keep.
Your response will not have a list of contacts because there could be network and bandwidth issues when updating thousands of contacts. Instead your response will include all of the IDs of the contacts that were successfully created.
We'll also include a property with issues that will identify the index (row) of the issue as well as the errors (headers) where the issue happened.
If you're testing with the example above, there should be an error at index 2 (Thor), with the errors showing email
since the email is missing the .com
.
Your response should look like this.
Using Common Props
Using JSON with Common Props
You can also use common properties when sending JSON data directly to the API.
By using common properties, you can ensure that specific values are applied to all items in the batch, simplifying the process of creating or updating multiple items with consistent data.