Create an audience

Request

You can create a new audience by making a POST request to https://api.intercom.io/audiences.

Requires the read_write_audiences OAuth scope.

Security

bearerAuth

Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:2.17

Bodyapplication/jsonrequired

namestringrequired

The name of the audience.

Example:"VIP Customers"

predicatesArray of objects(Predicate)

The predicates that define which contacts belong to the audience.

Example:

[
  {
    "attribute": "company.name",
    "type": "string",
    "comparison": "contains",
    "value": "Acme"
  }
]

role_predicatesArray of objects(Predicate)

Role-based predicates that further filter audience membership by contact role. Defaults to all three contact roles when omitted.

Example:

[
  {
    "attribute": "role",
    "type": "role",
    "comparison": "in",
    "value": [ … ]
  }
]

curl -i -X POST \
  https://api.intercom.io/audiences \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.17' \
  -d '{
    "name": "VIP Customers",
    "predicates": [
      {
        "attribute": "company.name",
        "type": "string",
        "comparison": "contains",
        "value": "Acme"
      }
    ],
    "role_predicates": [
      {
        "attribute": "role",
        "type": "role",
        "comparison": "in",
        "value": [
          "user_role",
          "contact_role",
          "visitor_role"
        ]
      }
    ]
  }'

Responses

Audience created

Bodyapplication/json

typestringread-only

The type of object.

Value:"audience"

Example:"audience"

idstringread-only

The unique identifier representing the audience.

Example:"123"

namestring

The name of the audience. Returned HTML-escaped, for example & as &.

Example:"VIP Customers"

predicatesArray of objects(Predicate)

The predicates that define which contacts belong to the audience.

Example:

[
  {
    "attribute": "company.name",
    "type": "string",
    "comparison": "contains",
    "value": "Acme"
  }
]

role_predicatesArray of objects(Predicate)

Role-based predicates that further filter audience membership by contact role.

Example:

[
  {
    "attribute": "role",
    "type": "role",
    "comparison": "in",
    "value": [ … ]
  }
]

created_atintegerread-only

The time the audience was created as a Unix timestamp.

Example:1717200000

updated_atintegerread-only

The time the audience was last updated as a Unix timestamp.

Example:1717200000

Response

{
  "type": "audience",
  "id": "789",
  "name": "VIP Customers",
  "predicates": [
    { … }
  ],
  "role_predicates": [
    { … }
  ],
  "created_at": 1717200000,
  "updated_at": 1717200000
}