Skip to content
Unless Docs

Rest API

Create or update an audience

POST
/api/v1/audiences

Create a new audience, or update an existing one by passing its ruleId. An audience is a reusable visitor segment defined by a targeting rule, used to scope personalizations and AI behaviour.

Use cases

  • Segmentation: Create audiences for visitor groups you want to target, e.g. returning visitors or visitors from a specific campaign
  • Account setup: Provision standard audiences when configuring a new workspace
  • Maintenance: Update the rule or name of an existing audience by passing its ruleId

Notes

  • Omit ruleId to create a new audience, pass it to update that audience
  • The rule field is a JSON string containing the targeting rule expression
  • Use the get audiences endpoint to inspect existing audiences and their rule format first

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
x-api-key
required
string

Your API key from account settings.

x-user-email
required
string

The email address of your user.

x-account-id
required
string

The ID of your account. You can find this in the account settings.

x-website-id
required
string

The ID of the workspace you want to use.

Request Body required

Section titled “Request Body required ”
object
ruleId

ID of an existing audience to update. Omit to create a new audience.

string
name
required

Display name of the audience.

string
rule
required

JSON string containing the targeting rule expression.

string
state
required

State of the audience.

string
Allowed values: draft live stopped
duration
One of:
number
durationType

Unit for the duration field.

string
Allowed values: minutes hours days
audienceTags

Tags used to categorise and filter audiences.

Array<string>

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The created or updated audience.

object
audience
object
accountId

The account ID that owns this audience.

string
websiteId

The website this audience belongs to.

string
ruleId

Unique identifier for this audience.

string
name

Display name of the audience.

string
state

Current state of the audience.

string
Allowed values: draft live stopped
rule

JSON string containing the targeting rule expression.

string
duration
One of:
number
durationType

Unit for the duration field.

string
Allowed values: minutes hours days
createdDate

Unix timestamp (ms) when the audience was created.

number
updatedDate

Unix timestamp (ms) when the audience was last updated.

number
disabled

Whether the audience is disabled. Disabled audiences are excluded from evaluation.

boolean
readOnly

Whether this audience can be modified.

boolean
audienceTags

Tags used to categorise and filter audiences.

Array<string>
Example
{
  "audience": {
    "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ruleId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "Returning visitors",
    "state": "live",
    "rule": "{\"and\":[{\"field\":\"visits\",\"operator\":\"greaterThan\",\"value\":\"1\"}]}",
    "duration": 30,
    "durationType": "days",
    "audienceTags": [
      "lifecycle"
    ]
  }
}

400

Section titled “400 ”

Bad request - missing or invalid body.

401

Section titled “401 ”

Unauthorized - invalid API key.