Contacts

Create & Update Contacts

# Create Contact(s)

This API will allow you to create a single contact using a traditional REST approach or many contacts at once using a csv or excel file encoded as a base64 data URL or public web URL. There's a soft cap of about 7.5MB for the base64 URL.

Typically, when creating anything we'll respond with the newly created object. However, because a CSV could have a very large number of contacts, the response for the CSV-created contacts will be different. More details on that below.

# Create Single Contact

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

        const data = {
  name: "Jamie Jones",
};

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

      

# 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." After the group is created you'll be able to nest contacts into the group by updating the group contact.

        const data = {
  name: "My Group",
  type: "group",
};

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

      

# Use CSV

A CSV will create many contacts at once. The following headers are required for the CSV file:

• Name - The name of the contact. If you have the name split by First Name and Last Name, you can pass that in instead.
• Email - The email of the contact. We will validate the emails. Any emails that are not valid will result in the contact not being added.
• Phone - The phone of the contact. Like the email, if it's not a valid phone the contact will not be added.
• Address - The address of the contact as a string.
• Address Line2 - The unit number for the contact's address if it's not part of the Address string.
• Type - If the contact is a group, it should be added. If omitted, it will default to person.
• Groups - The groups this contact is part of. Because the group will not be created yet, we'll look at the Name property and if it matches one of the groups from the Groups field, we'll associate that contact with a group. A demo of this is below.
• metadata - You are able to encode metadata from the CSV using dot notation. In the example below, each contact will have a csv_import property added to the metadata with the value of "yes".

# Example CSV

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

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

        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 contact IDs and message may differ slightly but your response should look like this.

        {
  "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"
}

      

# Update Contact

To update a contact, you'll need to pass the contact's ID along with any properties that you want to manage.

# Update Person

The address field can also include the address ID or location ID and we'll parse it successfully.

        const data = {
  name: "Jamie Jones",
  email: "jamie@packagex.xyz",
  phone: "+11234567890",
  address: "500 7th Ave, New York, NY 10018",
  address_line2: "Floor 10",
  metadata: {
    prop: "Whatever I want",
  },
  notes: "Will be out of town until Friday",
};

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

      

# Update Group Contact

To nest contacts in a group, add all of the IDs that you want to the children property. If any of these contacts need a special call out as the primary contact for the group, the contact can also be added to the primary contact array.

Once you have added children to the group_contacts, they will also show up in referenced_contacts field, to make it a little easier to construct potential UIs.

        const data = {
  name: "Finance Department",
  type: "group",
  group_contacts: {
    children: ["cont_rEMzyCyxJzuBzN4LyurAJV", "cont_kfxeR4ANbm9oC5RKztyc29"],
    primary: ["cont_kfxeR4ANbm9oC5RKztyc29"],
  },
};

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