# Audience selection

Objects that help you select and target an audience.


## Atomic selector {#atomicselector}

Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.

[Jump to examples ↓](#atomicselector-examples)

**One of:**

- `string`

  The simplest selector, which targets the entire audience.

- **Tag selector** `object`

  A tag is an arbitrary bit of metadata used for targeting devices. A tag specifier may or may not have an associated group declaration, indicating a `tag group` the tag belongs to, for example,  `{"tag": "silver-member", "group": "loyalty"}`. If no tag group is specified, the default `device` group is used.

  - **`group`** `string`
  - **`tag`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<string>`

- **Segment selector** `object`

  The Segment ID.

  - **`segment`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<string>`

- **Channel selector** `object`

  The unique channel identifier used to target an open channel device or web device, i.e., web browser. 

  - **`channel`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<string>`

- **Named User selector** `object`

  A `named_user` is an alternate, non-unique name, mapped to a user profile in a different database, e.g., CRM, that can be used to target devices associated with that profile.

  - **`named_user`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<string>`

- **Fire OS channel selector** `object`

  The unique channel identifier used to target a Fire OS device.

  - **`amazon_channel`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<string>`

- **Android channel selector** `object`

  The unique channel identifier used to target an Android device.

  - **`android_channel`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<string>`

- **Open channel selector** `object`

  The unique channel identifier used to target a device on an open platform.

  - **`open_channel`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<string>`

- `string`

  A long or short code the app is configured to send from. For example, `12345`.

- **SMS ID selector** `object`

  Selects a single SMS device. The `msisdn` must be `opted_in` to receive notifications.

  - **`msisdn`** `string` **REQUIRED**

    The recipient phone number.

    Min length: 1, Max length: 128

  - **`sender`** `string` **REQUIRED**

    The sender that the app is configured to send SMS messages from.

    Min length: 1, Max length: 128

- **Static list selector** `object`

  A `static_list` is a subset of your audience defined by a CSV file containing Channel IDs or Named Users.

  - **`static_list`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<string>`

- **Subscription List selector** `object`

  An single instance or array of subscription list IDs.

  - **`subscription_list`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<ref>`

- [Text Attribute selector]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#textattribute)

  An attribute object with a `TEXT` schema type. Evaluates for the inclusion or exclusion of a text (string) attribute on a channel or Named User.

- [Number Attribute selector]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#numberattribute)

  An attribute object with a `NUMBER` schema type. Performs value comparisons based on the number value for an attribute on a channel or Named User.

- [Date Attribute selector]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#dateattribute)

  An attribute object with a `DATE` schema type. Performs absolute date comparisons for ISO-formatted date values or a relative date comparisons given an integer `value` and `precision`, e.g., `days`, `months`. Use a date attribute to target a channel or Named User based on the date values.

- [JSON Attribute selector]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#jsonattribute)

  An attribute object with a `JSON` schema type. Performs value comparisons based on the JSON value for an attribute on a channel or Named User.

- **Alias selector** `object`

  A legacy mechanism used for mapping devices to a customer ID, e.g., a CRM identifier. Superseded by `named_user`.

  - **`alias`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<string>`

- **APID selector** `object`

  A legacy identifier for targeting Android and Windows devices, superseded by `android_channel`.

  - **`apid`** `object` **REQUIRED**
    **One of:**

    - `string`
    - `array<string>`

- [Activity audience object]({{< ref "/developer/rest-api/ua/schemas/event-segmentation/" >}}#activityobject)

  The `activity` object defines the target audience based on lifecycle actions or Custom Event activity, using comparison operators on activity count and recency. Optionally include a `where` object, which filters for specific activity values.

In the example to the right, the target audience is users who have opened your app from a notification from the "neowise" campaign at least twice, 3 days ago.


- `string`

  A special selector used in Pipelines to indicate that the audience of the push is composed of the device or devices that activated the trigger. See [Pipeline objects](/docs/developer/rest-api/ua/schemas/pipeline-objects/) for more information.


**Used in:**

- [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment)
- [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment)
- [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments)
- [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment)
- [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule)
- [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules)
- [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate)
- [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification)
- [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush)
- [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments)
- [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment)
- [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush)
- [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions)
- [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule)
- [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment)
- [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush)
- [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate)
- [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment)

**Examples**

*Example audience selection by tag*

```json
{
   "audience": {
      "tag": "sfGiants",
      "group": "favorite_teams"
   }
}

```

*Example SMS channel audience*

```json
{
    "audience" : {
        "sms_id" :  {
            "sender" : "12345",
            "msisdn" : "15552243311"
        }
    }
}

```

*Example audience segment*

```json
{
    "audience" : {
        "segment" : "<segment-id>"
    }
}

```

*Example audience of Named Users*

```json
{
   "audience" : {
      "named_user" : "user-id-54320"
   }
}

```

*Example audience of static list*

```json
{
   "audience" : {
      "static_list" : "name_of_list"
   }
}

```

---

## Audience selector (max 100) {#audienceselector100}

An audience selector forms the expression that determines the set of channels to target.

**One of:**

- [Compound selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#compoundselector)

  Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

- [Atomic selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#atomicselector)

  Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.


**Used in:**

- [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions)

---

## Audience selector (max 1000) {#audienceselector1000}

An audience selector forms the expression that determines the set of channels to target.

**One of:**

- [Compound selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#compoundselector)

  Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

- [Atomic selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#atomicselector)

  Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.


**Used in:**

- [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment)
- [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments)
- [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment)
- [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule)
- [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules)
- [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate)
- [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification)
- [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush)
- [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments)
- [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush)
- [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule)
- [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush)
- [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate)
- [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment)

---

## Compound selector {#compoundselector}

Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

[Jump to examples ↓](#compoundselector-examples)

**One of:**

- **AND selector** `object`

  AND selector

  - **`AND`** `array`

    Min items: 1, Max items: 10

    **One of:**

    - [Compound selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#compoundselector)

      Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

    - [Atomic selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#atomicselector)

      Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.


- **OR Selector** `object`

  OR selector

  - **`OR`** `array`

    Min items: 1, Max items: 10

    **One of:**

    - [Compound selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#compoundselector)

      Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

    - [Atomic selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#atomicselector)

      Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.


- **NOT Selector** `object`

  NOT selector

  - **`NOT`** `object`
    **One of:**

    - [Compound selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#compoundselector)

      Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.

    - [Atomic selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#atomicselector)

      Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.



**Used in:**

- [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment)
- [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment)
- [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments)
- [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment)
- [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule)
- [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules)
- [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate)
- [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification)
- [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush)
- [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments)
- [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment)
- [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush)
- [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions)
- [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule)
- [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment)
- [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush)
- [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate)
- [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment)

**Examples**

*Example with implicit `OR`*

```json
{
   "audience" : {
      "tag" : ["apples", "oranges", "bananas"]
   }
}

```

*Example with nested selectors*

```json
{
   "audience": {
      "AND": [
         {"OR": [
            {"tag": "sports"},
            {"tag": "entertainment"}
         ]},
         {"tag": "language_en"}
      ]
   }
}

```

*Example `NOT` selector*

```json
{
   "audience": {
      "AND": [
         { "tag": "Federer fan" },
         { "NOT":
            { "tag": "Messi fan" }
         }
      ]
   }
}

```

---