Skip to main content
API docs by Redocly

Developer API (2.0.0)

Download OpenAPI specification:Download

Audience

Operations about audiences.

Get a list of audiences

This endpoint requires the following permission(s): audiences:audiences:read. This endpoint belongs to the Audiences domain, which has a default rate limit of 60 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": null,
  • "url": "/v2/projects/proj1ab2c3d4/audiences"
}

Create an audience

This endpoint requires the following permission(s): audiences:audiences:read_write. This endpoint belongs to the Audiences domain, which has a default rate limit of 60 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

Request Body schema: application/json
required
name
required
string [ 1 .. 256 ] characters

The name of the audience

required
object (AudienceRules)

The audience membership rules. A subscriber matches the audience when any group matches (groups are combined with OR); within a group all conditions must match (conditions are combined with AND).

required
Array of objects

The condition groups, combined with OR.

Array
required
Array of objects (AudienceRuleCondition)

The conditions in the group, combined with AND.

Array
required
string or string

The subscriber field evaluated by the condition. Custom subscriber attributes are referenced as customAttribute:<key> (e.g. customAttribute:plan_tier).

operator
required
string
Enum: "is" "isNot" "isAnyOf" "isNotAnyOf" "greaterThan" "greaterThanOrEqual" "lessThan" "lessThanOrEqual" "equal" "notEqual" … 13 more

The comparison operator applied to the field.

value
string
Default: ""

The value the field is compared against. May be empty for operators that do not take a value (e.g. isEmpty, isNotEmpty). Multi-value operators (isAnyOf, isNotAnyOf, containsAnyOf) take comma-separated values. For latestProduct, equality operators use product ids (prod...), while substring operators use raw product identifier text. For anyActiveStore, use store identifiers such as app_store.

currency
string
Enum: "USD" "EUR" "GBP" "AUD" "CAD" "JPY" "BRL" "KRW" "CNY" "MXN" … 4 more

Currency for a totalSpent comparison. Omitted values are interpreted as USD. Must be omitted for isEmpty and isNotEmpty.

Responses

Request samples

Content type
application/json
{
  • "name": "Active subscribers",
  • "rules": {
    }
}

Response samples

Content type
application/json
{
  • "object": "audience",
  • "id": "aud1a2b3c4d5e6f7g8",
  • "project_id": "proj1ab2c3d4",
  • "customer_list_id": "list1a2b3c4d",
  • "name": "Active subscribers",
  • "rules": {
    },
  • "created_at": 1658399423658,
  • "updated_at": 1658399423658,
  • "stats": {
    },
  • "customer_sample": [
    ],
  • "used_by": {
    }
}

Preview audience members

This endpoint requires the following permission(s): audiences:audiences:read. This endpoint belongs to the Audiences domain, which has a default rate limit of 60 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

Request Body schema: application/json
required
One of
audience_uuid
required
string

UUID of the saved audience.

Responses

Request samples

Content type
application/json
Example
{
  • "audience_uuid": "abc12345"
}

Response samples

Content type
application/json
{
  • "object": "audience_preview",
  • "stats": {
    },
  • "customer_sample": [
    ]
}

Get audience filter options

Returns the known values for audience rule condition fields whose options are derived from the project's data (attribution fields, price experiments, and custom attributes). Custom attributes are returned as dynamic fields using the format customAttribute:<key>; requesting customAttribute expands to every known custom attribute. Fields with a fixed set of values (e.g. country, platform, status) are not served by this endpoint. This endpoint requires the following permission(s): audiences:audiences:read. This endpoint belongs to the Audiences domain, which has a default rate limit of 60 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

query Parameters
required
Array of strings or strings non-empty
Example: fields=mediaSource

Audience condition fields to load options for. Custom attributes use the field format customAttribute:<key>; customAttribute alone expands to every known custom attribute.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": null,
  • "url": "/v2/projects/proj1ab2c3d4/audiences/filter_options"
}

Get an audience

This endpoint requires the following permission(s): audiences:audiences:read. This endpoint belongs to the Audiences domain, which has a default rate limit of 60 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

audience_id
required
string [ 1 .. 255 ] characters
Example: aud1a2b3c4d5e6f7g8

ID of the audience

query Parameters
expand
Array of strings[ items [ 1 .. 5000 ] characters ]
Items Enum: "stats" "customer_sample" "used_by"
Example: expand=stats

Specifies which fields in the response should be expanded. Accepted values are: stats (requires audiences:audiences:read permission), customer_sample (requires audiences:audiences:read permission), used_by (requires audiences:audiences:read permission).

Responses

Response samples

Content type
application/json
{
  • "object": "audience",
  • "id": "aud1a2b3c4d5e6f7g8",
  • "project_id": "proj1ab2c3d4",
  • "customer_list_id": "list1a2b3c4d",
  • "name": "Active subscribers",
  • "rules": {
    },
  • "created_at": 1658399423658,
  • "updated_at": 1658399423658,
  • "stats": {
    },
  • "customer_sample": [
    ],
  • "used_by": {
    }
}

Update an audience

This endpoint requires the following permission(s): audiences:audiences:read_write. This endpoint belongs to the Audiences domain, which has a default rate limit of 60 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

audience_id
required
string [ 1 .. 255 ] characters
Example: aud1a2b3c4d5e6f7g8

ID of the audience

Request Body schema: application/json
required
non-empty
name
string [ 1 .. 256 ] characters

The name of the audience

object (AudienceRules)

The audience membership rules. A subscriber matches the audience when any group matches (groups are combined with OR); within a group all conditions must match (conditions are combined with AND).

required
Array of objects

The condition groups, combined with OR.

Array
required
Array of objects (AudienceRuleCondition)

The conditions in the group, combined with AND.

Array
required
string or string

The subscriber field evaluated by the condition. Custom subscriber attributes are referenced as customAttribute:<key> (e.g. customAttribute:plan_tier).

operator
required
string
Enum: "is" "isNot" "isAnyOf" "isNotAnyOf" "greaterThan" "greaterThanOrEqual" "lessThan" "lessThanOrEqual" "equal" "notEqual" … 13 more

The comparison operator applied to the field.

value
string
Default: ""

The value the field is compared against. May be empty for operators that do not take a value (e.g. isEmpty, isNotEmpty). Multi-value operators (isAnyOf, isNotAnyOf, containsAnyOf) take comma-separated values. For latestProduct, equality operators use product ids (prod...), while substring operators use raw product identifier text. For anyActiveStore, use store identifiers such as app_store.

currency
string
Enum: "USD" "EUR" "GBP" "AUD" "CAD" "JPY" "BRL" "KRW" "CNY" "MXN" … 4 more

Currency for a totalSpent comparison. Omitted values are interpreted as USD. Must be omitted for isEmpty and isNotEmpty.

Responses

Request samples

Content type
application/json
{
  • "name": "Active subscribers",
  • "rules": {
    }
}

Response samples

Content type
application/json
{
  • "object": "audience",
  • "id": "aud1a2b3c4d5e6f7g8",
  • "project_id": "proj1ab2c3d4",
  • "customer_list_id": "list1a2b3c4d",
  • "name": "Active subscribers",
  • "rules": {
    },
  • "created_at": 1658399423658,
  • "updated_at": 1658399423658,
  • "stats": {
    },
  • "customer_sample": [
    ],
  • "used_by": {
    }
}