Batches

Create & Update Batches

Create Batch(s)

POST

`/v1/batches`

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.

        const data = {
  mode: "mixed",
  action: "merge",
  resource: "contact",
  data: [
    {
      name: "Jamie Jones",
      email: "jamie@packagex.xyz",
      phone: "+11234567890",
    },
    {
      name: "Steve Rogers",
      email: "s.rogers@packagex.xyz",
      phone: "+11234567891",
    },
  ],
};

fetch(`https://api.packagex.io/v1/batches`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

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")

        const data = {
  mode: "mixed",
  action: "merge",
  resource: "contact",
  data: [
    {
      id: "ctct_119hckKY7SJeHDdq8SBKXe",
      phone: "+11234567892",
    },
    {
      id: "ctct_11Mvk2DY6rvZMSupThSp7V",
      phone: "+11234566893",
    }
  ],
  properties: {
    groups: {
      set: ["grp_1b8aUvyn4SyUD6SBUiaeD5"]
    },
    locations: {
      add: ["loc_11BHHB8ax6bRKyzb5vqWDw", "loc_1291JfypM9jp3tg3sHsPDu"],
    }
  }
};

fetch(`https://api.packagex.io/v1/batches`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

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."

        const data = {
  mode: "mixed",
  action: "merge",
  resource: "group",
  data: [
    {
      name: "Finance Department",
      resource: "contact", // contact or location
      group_contacts: {
        children: ["contact_123", "contact_456"],
        primary: ["contact_456"],
      },
    },
  ],
};

fetch(`https://api.packagex.io/v1/batches`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

Create Shipment

Only the merge action is applicable for shipments. The shipment requires a tracking_number.

        const data = {
  mode: "mixed",
  action: "merge",
  resource: "shipment",
  data: [
    {
      tracking_number: "1Z999AA10123456784",
    },
  ],
};

fetch(`https://api.packagex.io/v1/batches`, {
  method: "POST",
  headers: {
    "PX-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

Create Tracker

Only the merge action is applicable for trackers. The tracker requires a tracking_number.

        const data = {
  mode: "mixed",
  action: "merge",
  resource: "tracker",
  data: [
    {
      tracking_number: "1Z999AA10123456784",
    },
  ],
};

fetch(`https://api.packagex.io/v1/batches`, {
  method: "POST",
  headers: {
    "PX-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

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

Name	Email	Phone	Type	Groups	Address	metadata.csv_import
Jamie Jones	jamie@packagex.xyz	1234567890			500 7th Ave, Floor 10, New York, NY 10018	yes
Evelyn Parker	tony@packagex.xyz			Stark Industries, Avengers		yes
Lucas Bennett	messed_up@aol			Avengers		yes
Sophia Martinez				Avengers		yes
Liam Thompson			group			yes
Olivia Johnson			group			yes

We've already encoded this table into a base64 data URL to make it easier to test.

json

        {
  "csv_url": "data:text/csv;base64,TmFtZSxFbWFpbCxQaG9uZSxUeXBlLEdyb3VwcyxBZGRyZXNzLG1ldGFkYXRhLmNzdl9pbXBvcnQNCkphbWllIEpvbmVzLGphbWllQHBhY2thZ2V4Lnh5eiwsLCwiNTAwIDd0aCBBdmUsIEZsb29yIDEwLCBOZXcgWW9yaywgTlkgMTAwMTgiLHllcw0KSXJvbiBNYW4sdG9ueUBwYWNrYWdleC54eXosLCwiU3RhcmsgSW5kdXN0cmllcywgQXZlbmdlcnMiLCx5ZXMNClRob3IsbWVzc2VkX3VwQGFvbCwsLEF2ZW5nZXJzLCx5ZXMNCkJsYWNrIFdpZG93LCwsLEF2ZW5nZXJzLCx5ZXMNCkF2ZW5nZXJzLCwsZ3JvdXAsLCx5ZXMNClN0YXJrIEluZHVzdHJpZXMsLCxncm91cCwsLHllcw=="
}

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.

DANGER

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.

        const data = {
  csv_url: "data:text/csv;base64,TmFtZSxFbWFpbCxQaG9uZSxUeXBlLEdyb3VwcyxBZGRyZXNzLG1ldGFkYXRhLmNzdl9pbXBvcnQNCkphbWllIEpvbmVzLGphbWllQHBhY2thZ2V4Lnh5eiwsLCwiNTAwIDd0aCBBdmUsIEZsb29yIDEwLCBOZXcgWW9yaywgTlkgMTAwMTgiLHllcw0KSXJvbiBNYW4sdG9ueUBwYWNrYWdleC54eXosLCwiU3RhcmsgSW5kdXN0cmllcywgQXZlbmdlcnMiLCx5ZXMNClRob3IsbWVzc2VkX3VwQGFvbCwsLEF2ZW5nZXJzLCx5ZXMNCkJsYWNrIFdpZG93LCwsLEF2ZW5nZXJzLCx5ZXMNCkF2ZW5nZXJzLCwsZ3JvdXAsLCx5ZXMNClN0YXJrIEluZHVzdHJpZXMsLCxncm91cCwsLHllcw==", //prettier-ignore
  overwrite: false,
};

fetch(`https://api.packagex.io/v1/contacts`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

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.

json

        {
  "message": "5 contacts added and 5 deleted while 1 contact was not updated because of some issues",
  "data": {
    "ids": [
      "cont_rEMzyCyxJzuBzN4LyurAJV",
      "cont_kfxeR4ANbm9oC5RKztyc29",
      "cont_fABxkxi6uL2SgnvjWiiLRC",
      "cont_tBwX2KqwCGMbY959zqjP5m",
      "cont_tt6TgRRtunPWS9uFuWsrc1"
    ],
    "issues": [
      {
        "index": 2,
        "errors": ["email"]
      }
    ],
    "deleted": 5
  },
  "status": 200,
  "errors": [],
  "code": null,
  "pagination": null,
  "endpoint": "/v1/contacts"
}

Using Common Props

Using JSON with Common Props

You can also use common properties when sending JSON data directly to the API.

        const data = {
  resource: "contact",
  mode: "sync",
  action: "merge",
  location_id: "loc_456",
  properties: {
    role: "admin",
    active: true,
  },
  data: [
    { id: "123", name: "John Doe" },
    { id: "456", name: "Jane Doe" },
  ],
};

fetch(`https://api.packagex.io/v1/batches`, {
  method: "POST",
  headers: {
    "PX-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

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.

Example of Using Base64 with Common Props

        const data = {
  resource: "contact",
  mode: "mixed",
  action: "merge",
  location_id: "loc_456",
  properties: {
    role: "admin",
    active: true,
  },
  data: "data:text/csv;base64,TmFtZSxFbWFpbCxQaG9uZSxUeXBlLEdyb3VwcyxBZGRyZXNzLG1ldGFkYXRhLmNzdl9pbXBvcnQNCkphbWllIEpvbmVzLGphbWllQHBhY2thZ2V4Lnh5eiwsLCwiNTAwIDd0aCBBdmUsIEZsb29yIDEwLCBOZXcgWW9yaywgTlkgMTAwMTgiLHllcw0KSXJvbiBNYW4sdG9ueUBwYWNrYWdleC54eXosLCwiU3RhcmsgSW5kdXN0cmllcywgQXZlbmdlcnMiLCx5ZXMNClRob3IsbWVzc2VkX3VwQGFvbCwsLEF2ZW5nZXJzLCx5ZXMNCkJsYWNrIFdpZG93LCwsLEF2ZW5nZXJzLCx5ZXMNCkF2ZW5nZXJzLCwsZ3JvdXAsLCx5ZXMNClN0YXJrIEluZHVzdHJpZXMsLCxncm91cCwsLHllcw==",
};

fetch(`https://api.packagex.io/v1/batches`, {
  method: "POST",
  headers: {
    "PX-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

Create & Update Batches

# Create Batch(s)

# Create Contacts

# Create Group

# Create Shipment

# Create Tracker

# Use CSV

# Example CSV

# Using Common Props

# Using JSON with Common Props

# Example of Using Base64 with Common Props

On this page

Create Batch(s)

Create Contacts

Create Group

Create Shipment

Create Tracker

Use CSV

Example CSV

Using Common Props

Using JSON with Common Props

Example of Using Base64 with Common Props