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
https://personalize-api.contentstack.com/audiencesThe 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.
{
"name": "US Visitors",
"description": "Website visitors from the US",
"definition": {
"__type": "RuleCombination",
"combinationType": "AND",
"rules": [
{
"__type": "Rule",
"attribute": {
"__type": "PresetAttributeReference",
"ref": "COUNTRY"
},
"attributeMatchCondition": "STRING_EQUALS",
"attributeMatchOptions": {
"__type": "StringMatchOptions",
"value": "US"
},
"invertCondition": false
}
]
}
}{
"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
https://personalize-api.contentstack.com/audiencesThe 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.
[
{
"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
https://personalize-api.contentstack.com/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.
{
"name": "Australian",
"description": "Australian Audience description",
"definition": {
"__type": "RuleCombination",
"combinationType": "AND",
"rules": [
{
"__type": "Rule",
"attribute": {
"__type": "PresetAttributeReference",
"ref": "COUNTRY"
},
"attributeMatchCondition": "STRING_EQUALS",
"attributeMatchOptions": {
"__type": "StringMatchOptions",
"value": "AU"
},
"invertCondition": false
}
]
}
}{
"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
https://personalize-api.contentstack.com/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.
The audience was deleted successfully