Create a new audience

post

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/audiences/add

Defines a new audience within a project. Requires a name, type (permanent, transient, segmentation), and a set of rules defining the audience criteria. Rules can be based on visitor data (browser, device, geo-location, language, visit count, cookie values), traffic sources (UTM parameters, referrer), page tags, or JavaScript conditions. The Knowledge Base article "Define an Advanced Audience" lists many available conditions.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

account_id

integer

required

ID of the account that owns the retrieved/saved data

project_id

integer

required

ID of the project into which the audience is to be stored

Body Params

description

string

length ≤ 500

An optional, more detailed explanation of the audience's purpose or criteria, aiding in identification and management.

status

string

enum

The status of an audience:

active: The audience is currently active and can be used for targeting experiences.
archived: The audience is no longer active and cannot be used for new experiences, but its definition and past usage data are preserved. Archived audiences can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."

Allowed:

name

string

required

length ≤ 100

A user-defined, friendly name for the audience (e.g., "New Visitors from USA", "Repeat Purchasers - Mobile"). This name appears in the Convert UI when selecting audiences for experiences.

selected_default

boolean

If true, this audience will be automatically pre-selected when creating new experiences within the project. Useful for commonly targeted segments.

type

string

enum

required

Defines the behavior and persistence of an audience that does not use URL-based conditions in its rules.

permanent: Once a visitor matches the audience criteria, they are permanently considered part of this audience for future sessions and evaluations, even if their characteristics change later. The matching is checked only at the initial bucketing time.
transient: A visitor must match the audience criteria upon each evaluation (e.g., on every page load or when an experiment is rechecked) to be included. If conditions are no longer met, the visitor is no longer part of the audience for that specific evaluation. For Full Stack projects, only transient and segmentation (if applicable without URL rules) are valid.

Allowed:

rules

object | null

required

Similar to RuleObject, but the individual RuleElementNoUrl conditions within OR_WHEN arrays cannot include URL-based matching types. Used for 'permanent' or 'transient' audiences where URL context is not persistently evaluated or relevant for the audience type.

Responses

201Detailed information for a single audience, including its name, type, status, and the rules (visitor data, traffic source, cookie values, JS conditions) that define its criteria.

defaultIndicates an error occurred while processing the request. The code provides an HTTP status code, message offers a human-readable explanation or an array of validation errors, and fields (if present) specifies which input fields were problematic.