Audience management

A marketing audience is a special type of list in Nutshell, consisting of any number of contacts. Unlike a normal saved list, audiences are not dynamic – people need to be manually added and removed in Nutshell. This guide will walk you through creating, updating, and managing different audience memberships.

Creating a new audience

API reference for creating an audience

You may only create one audience per request.

Request URL:

https://app.nutshell.com/rest/audiences

Example request data:

{
 "emAudiences": [
   {
       "name": "Your Audience Name"
   }
 ]
}

Creating a person and putting them in an audience

API reference for creating a person

Request URL:

https://app.nutshell.com/rest/contacts

Example request data:

{
  "contacts": [
    {
      "name": "Jane Doe",
      "links": {
        "emAudiences": [
          "1-emAudiences",
          "2-emAudiences"
        ]
      }
    }
  ]
}

Updating audience membership of a person

API reference for updating a person

Request URL:

https://app.nutshell.com/rest/contacts/{id}-contacts

Where {id} is the id of the contact to update.

You can update audience membership of a person in a few ways using a PATCH request on a contact.

1. Add a person to audiences by passing an array of data. The path must end in /- for add operations, and the value must be the API ID of the audience you want to add the person to.

Example request data:

[
  {
    "op": "add",
    "path": "/contacts/0/links/emAudiences/-",
    "value": "1-emAudiences"
  },
  {
    "op": "add",
    "path": "/contacts/0/links/emAudiences/-",
    "value": "2-emAudiences"
  }
]

2. Remove a person from audiences by passing an array of data. The path must end with the API ID of the audience you want to remove the person from, and there is no need to include a “value”.

Example request data:

[
  {
    "op": "remove",
    "path": "/contacts/0/links/emAudiences/2-emAudiences"
  },
  {
    "op": "remove",
    "path": "/contacts/0/links/emAudiences/3-emAudiences"
  }
]

3. Replace a person’s current audience memberships with new ones. This will remove the person from all their current audience memberships, and add them to the audiences passed. The path ends in emAudiences, and you can pass an array of audience API IDs to replace the person’s current memberships with. Passing an empty array ([]) will remove the person from all audiences.

Example request data:

[
  {
    "op": "replace",
    "path": "/contacts/0/links/emAudiences",
    "value": ["2-emAudiences", "3-emAudiences"]
  }
]