Audience filters

For text, number, boolean and date attributes, SDK methods and audience operators, see Tags.

A saved audience is a named set of device filters. Use its ID as audience.audience_id in a send request. To create one, follow target an audience.

The filters

An audience supports up to 20 filters. All filters must match (AND). An empty filter list matches every device in the app.

For locale, timezone_id, app_version, app_build, os_version tag and user_tag, choose exactly one comparison: value for equality, in for any value in a list, or not_in to exclude the listed values. Lists contain 1-50 strings, each 1-256 characters.

Tag filters also support exists: true (key is present) or exists: false (key is absent). Do not combine comparisons in the same filter. Filters still combine with AND.

{
  "filters": [
    { "field": "locale", "in": ["fr-FR", "fr-CA"] },
    { "field": "tag", "key": "plan", "not_in": ["free"] },
    { "field": "tag", "key": "region", "exists": true }
  ]
}

not_in matches devices without the tag

not_in matches every device whose value is not in the list, including devices that do not carry the tag or field at all. { "field": "tag", "key": "plan", "not_in": ["free"] } matches pro devices and devices that never set plan. in and value never match an absent tag.

An exclusion segment, "every country except these", therefore needs two filters on the same tag: not_in for the excluded values and exists: true so devices that never set the tag stay out.

{
  "filters": [
    { "field": "tag", "key": "country", "not_in": ["FR", "BE"] },
    { "field": "tag", "key": "country", "exists": true }
  ]
}

Country and region are your own tags

Carillon does not infer a device's country from its locale, timezone or IP address. For country or region targeting, set a tag from your own user record, such as country with an ISO 3166-1 alpha-2 code, with setTags() at sign-in and whenever the record changes. Your backend is the source of that value, so the same code you use elsewhere is the one you filter on.

{
  "name": "Active iOS",
  "definition": {
    "filters": [
      { "field": "platform", "value": "ios" },
      { "field": "last_active", "within_days": 30 },
      { "field": "tag", "key": "plan", "value": "pro" }
    ]
  }
}

This definition matches iOS devices active in the last 30 days with tags.plan equal to pro.

What reachable counts

POST /v1/apps/{appId}/audiences/preview returns the number of matching devices that are opted in and not invalidated. It does not save the definition.

{ "reachable": 1284 }

The count reflects current device state and can change before a send. All send targets exclude devices that are opted out or invalidated, including explicit device IDs and external user IDs. These devices create no deliveries and do not count as failed sends.

When recipients are selected

The campaign uses the saved audience’s latest filters when recipient resolution begins. Edits made before that point apply to scheduled campaigns too. Once resolution starts, the filters are frozen for retries and every timezone wave of that campaign. If the audience has been deleted, the campaign keeps its creation-time copy.

Devices are selected when sending begins. For a scheduled campaign, devices registered later can match the copied filters when the campaign runs. For local-time schedules, selection happens per timezone wave.

Names and IDs

Names must be unique within an app. A duplicate name returns 409 duplicate_audience_name. A send using an unknown audience ID, including one from another app, returns 422 unknown_audience.

Related pages

Target an audience · Manage audiences · API reference

Shared user tags

Use user tags for attributes shared by every device of a user. Combine user_tag and tag filters to target a user attribute and a device attribute without copying data between them. The dashboard labels them User tag and Device tag. A device without an external ID or a matching profile has no user tags: exists: false and not_in match it; equality and in do not. Numbers and booleans are compared as strings ("3", "true"), as for device tags.

Build an audience in the dashboard

Open Audiences → New audience, name it, and add filters. Search languages and timezones by name or code. App versions, device tag keys and values, and user tag keys and values are suggested from reachable live devices in the app. You can also enter a value before any device reports it. Locale comparisons are exact: fr and fr-FR are different values.

For Is one of and Is none of, select several values; remove a selected pill to remove that value. Last active → Active within the last 30 days means the 30 days preceding each send, based on device activity reported to Carillon. The reach preview excludes opted-out, invalidated and test devices.