1. Batches
  2. Create & Update Batches

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 Single Contact

The only required property for a contact is the name, but we recommend adding more information like the email or phone.

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

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

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

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

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

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

js
        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

js
        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),
});