---
title: "Audiences"
description: "<p>Audiences refer to a specific group of people who share certain characteristics, behaviors, or interests. These groups are identified based on various criteria such as demographics (age, gender, location), behavior (buying habits, website visits), interests (hobbies, favorite types of products), and more.</p>"
url: "https://www.contentstack.com/docs/developers/apis/personalize-management-api/audiences"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-04-24"
---

# Audiences

Audiences refer to a specific group of people who share certain characteristics, behaviors, or interests. These groups are identified based on various criteria such as demographics (age, gender, location), behavior (buying habits, website visits), interests (hobbies, favorite types of products), and more.

## Create an Audience

### Create an Audience

**POST** `/audiences`

The Create an Audience request lets you create a new audience in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The examples below provide a detailed explanation on creating audiences with various parameters.  
  

##### Create audience with Custom Attributes:

```
{
  "name": "Valuable US Visitors",
  "description": "US Visitors with an average order value greater than $1000",
  "definition": {
    "__type": "RuleCombination",
    "combinationType": "AND",
    "rules": [
      {
        "__type": "Rule",
        "attribute": {
          "__type": "PresetAttributeReference",
          "ref": "COUNTRY"
        },
        "attributeMatchCondition": "STRING_EQUALS",
        "attributeMatchOptions": {
          "__type": "StringMatchOptions",
          "value": "US"
        },
        "invertCondition": false
      },
      {
        "__type": "Rule",
        "attribute": {
          "__type": "CustomAttributeReference",
          "ref": "66702e03d84509d0106bec05"
        },
        "attributeMatchOptions": {
          "__type": "NumberMatchOptions",
          "value": 1000
        },
        "attributeMatchCondition": "NUMBER_GREATER_THAN",
        "invertCondition": false
      }
    ]
  }
}
```

This example creates an audience with Custom Attributes. We have two rules being matched here, the second one matching a custom attribute. The \_\_type on the attribute allows you to specify whether the attribute is Custom or Preset.  
  

##### Match Query Parameters:

```
{
  "name": "Black Friday Campaign",
  "description": "Visitors targeted with the Black Friday Campaign",
  "definition": {
    "__type": "RuleCombination",
    "combinationType": "AND",
    "rules": [
      {
        "__type": "Rule",
        "attribute": {
          "__type": "PresetAttributeReference",
          "ref": "QUERY_PARAMETERS"
        },
        "attributeMatchCondition": "JSON_MATCH",
        "attributeMatchOptions": {
          "__type": "JSONMatchOptions",
          "pointer": "/utm_campaign",
          "matchCondition": "STRING_EQUALS",
          "matchOptions": {
            "__type": "StringMatchOptions",
            "value": "BLACK_FRIDAY"
          },
          "invertCondition": false
        },
        "invertCondition": false
      }
    ]
  }
}
```

Query Parameters are a Preset Attribute. In this example, the query parameter utm\_campaign is matched for a BLACK\_FRIDAY value. The JSONMatchOptions type allow you to nest a matchOptions so that you can match specific values for the parameter.  
  

##### Match Date and Time:

```
{
  "name": "Black Friday Campaign",
  "description": "Visitors targeted with the Black Friday Campaign",
  "definition": {
    "__type": "RuleCombination",
    "combinationType": "AND",
    "rules": [
      {
        "__type": "Rule",
        "attribute": {
          "__type": "PresetAttributeReference",
          "ref": "QUERY_PARAMETERS"
        },
        "attributeMatchOptions": {
          "__type": "JSONMatchOptions",
          "pointer": "/utm_campaign",
          "matchCondition": "STRING_EQUALS",
          "matchOptions": {
            "__type": "StringMatchOptions",
            "value": "BLACK_FRIDAY"
          },
          "invertCondition": false
        },
        "attributeMatchCondition": "JSON_MATCH",
        "invertCondition": false
      },
      {
        "__type": "Rule",
        "attribute": {
          "__type": "PresetAttributeReference",
          "ref": "DATE_AND_TIME"
        },
        "attributeMatchCondition": "BETWEEN_TIME",
        "attributeMatchOptions": {
          "__type": "DateTimeMatchOptions",
          "startTime": "2024-11-29T00:00:00",
          "endTime": "2024-11-29T23:59:59",
          "useVisitorTimezone": true
        },
        "invertCondition": false
      }
    ]
  }
}
```

Date and Time is a Preset Attribute. In this example, we extend the Black Friday Campaign audience to also match only on the day of Black Friday. useVisitorTimezone allows us to evaluate the conditions in the visitors timezone.

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
{
  "name": "US Visitors",
  "description": "Website visitors from the US",
  "definition": {
    "__type": "RuleCombination",
    "combinationType": "AND",
    "rules": [
      {
        "__type": "Rule",
        "attribute": {
          "__type": "PresetAttributeReference",
          "ref": "COUNTRY"
        },
        "attributeMatchOptions": {
          "__type": "StringMatchOptions",
          "value": "US"
        },
        "attributeMatchCondition": "STRING_EQUALS",
        "invertCondition": false
      }
    ]
  },
  "project": "6c7787b333555469a8612227",
  "referredAttributes": [],
  "createdBy": "bxxxxxxxxxxxxxxxxx7",
  "updatedBy": "bxxxxxxxxxxxxxxxxx7",
  "createdAt": "2024-08-22T09:46:11.680Z",
  "updatedAt": "2024-08-22T09:46:11.680Z",
  "uid": "66c708e3fe314f5067826852",
  "createdByUserName": "Jane Doe",
  "updatedByUserName": "Jane Doe"
}
```

## Get all Audiences

### Get all Audiences

**GET** `/audiences`

The Get all Audiences request fetches the list of all the audiences in a project.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

#### Query Parameters

- **referredAttributes[]** (optional)
  Filter audiences by passing a list of attribute UIDs. The audiences referring to the given attributes will be returned.

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
[
  {
    "name": "Indian",
    "description": "",
    "definition": {
      "__type": "RuleCombination",
      "combinationType": "AND",
      "rules": [
        {
          "__type": "Rule",
          "attribute": {
            "__type": "PresetAttributeReference",
            "ref": "COUNTRY"
          },
          "attributeMatchOptions": {
            "__type": "StringMatchOptions",
            "value": "IN"
          },
          "attributeMatchCondition": "STRING_EQUALS",
          "invertCondition": false
        },
        {
          "__type": "Rule",
          "attribute": {
            "__type": "PresetAttributeReference",
            "ref": "DATE_AND_TIME"
          },
          "attributeMatchOptions": {
            "__type": "DateTimeMatchOptions",
            "value": "2023-09-28T18:40:10+00:00",
            "useVisitorTimezone": false
          },
          "attributeMatchCondition": "BEFORE_TIME",
          "invertCondition": false
        },
        {
          "__type": "Rule",
          "attribute": {
            "__type": "CustomAttributeReference",
            "ref": "6c7787b333555469a861222e"
          },
          "attributeMatchOptions": {
            "__type": "NumberMatchOptions",
            "value": 25
          },
          "attributeMatchCondition": "NUMBER_EQUAL_TO",
          "invertCondition": false
        },
        {
          "__type": "Rule",
          "attribute": {
            "__type": "PresetAttributeReference",
            "ref": "DEVICE_TYPE"
          },
          "attributeMatchOptions": {
            "__type": "StringMatchOptions",
            "value": "MOBILE"
          },
          "attributeMatchCondition": "STRING_EQUALS",
          "invertCondition": false
        },
        {
          "__type": "RuleCombination",
          "combinationType": "AND",
          "rules": [
            {
              "__type": "Rule",
              "attribute": {
                "__type": "PresetAttributeReference",
                "ref": "DEVICE_TYPE"
              },
              "attributeMatchOptions": {
                "__type": "StringMatchOptions",
                "value": "MOBILE"
              },
              "attributeMatchCondition": "STRING_EQUALS",
              "invertCondition": false
            }
          ]
        }
      ]
    },
    "project": "6c7787b333555469a8612227",
    "referredAttributes": [
      "6c7787b333555469a861222e"
    ],
    "createdBy": "bxxxxxxxxxxxx3",
    "updatedBy": "bxxxxxxxxxxxx6",
    "createdAt": "2024-03-13T15:39:51.645Z",
    "updatedAt": "2024-03-13T15:39:51.645Z",
    "uid": "6c7787b333555469a8612229",
    "createdByUserName": "Jane Doe",
    "updatedByUserName": "Jane Doe"
  }
]
```

## Update an audience

### Update an audience

**PUT** `/audiences/{uid}`

The Update an Audience request lets you update an existing audience in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

For more detailed request body documentation, please refer to the Create an Audience request.

#### URL Parameters

- **uid** (required)
  Enter the Audience UID to be updated.

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
{
  "name": "US Visitors",
  "description": "Visitors from the US",
  "definition": {
    "__type": "RuleCombination",
    "combinationType": "AND",
    "rules": [
      {
        "__type": "Rule",
        "attribute": {
          "__type": "PresetAttributeReference",
          "ref": "COUNTRY"
        },
        "attributeMatchOptions": {
          "__type": "StringMatchOptions",
          "value": "US"
        },
        "attributeMatchCondition": "STRING_EQUALS",
        "invertCondition": false
      }
    ]
  },
  "project": "6c7787b333555469a8612227",
  "referredAttributes": [],
  "createdBy": "bxxxxxxxxxxxxxxxxx7",
  "updatedBy": "bxxxxxxxxxxxxxxxxx7",
  "createdAt": "2024-08-22T09:46:11.680Z",
  "updatedAt": "2024-08-22T11:43:35.232Z",
  "uid": "66c708e3fe314f5067826852",
  "createdByUserName": "Jane Doe",
  "updatedByUserName": "Jane Doe"
}
```

## Delete an audience

### Delete an audience

**DELETE** `/audiences/{uid}`

The Delete an Audience request lets you delete an existing audience in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

#### URL Parameters

- **uid** (required)
  Enter the Audience UID to be deleted.

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
The audience was deleted successfully
```