Advanced filtering with AND/OR logic

With more advanced filtering features, you can express audience logic that cannot be represented by a flat list of filters.

Use these when you need to target participants who match one of several valid paths, such as:

• participants resident in one of several countries
• participants in a participant group who fall within a target age range
• participants who took a previous study and passed a screener, or participants who have not taken that study yet

How filter logic is evaluated

A study or filter set can contain leaf filters and composite groups.

Leaf filters are the standard select and range filters. See Filters Overview for examples of each.

Composite groups use filter_id: "and" or filter_id: "or" and put their child filters in selected_filters.

• and: every child filter in the group must match.
• or: at least one child filter in the group must match.
• A flat list of top-level filters is treated as an implicit and.

Flat OR within one attribute

For a select filter, multiple selected_values means “match any of these selected values”. The values are the choice IDs returned for that filter by the filters list endpoint.

For example, this selects participants resident in either of two countries:

1
{
2
  "filter_id": "current-country-of-residence",
3
  "selected_values": ["0", "1"]
4
}

You can use this form to simplify the query when the OR choices all belong to the same filter attribute.

OR across different filters

To match participants who satisfy one of several different filters, you can wrap the leaf filters in an or group.

For example, this matches participants who are either in the participant group or aged between 18 and 30:

1
{
2
  "filter_id": "or",
3
  "selected_filters": [
4
    {
5
      "filter_id": "participant_group_allowlist",
6
      "selected_values": ["<participant_group_id>"]
7
    },
8
    {
9
      "filter_id": "age",
10
      "selected_range": {
11
        "lower": 18,
12
        "upper": 30
13
      }
14
    }
15
  ]
16
}

Nested AND/OR groups

You can use nested composite groups when each OR branch has its own AND requirements.

For example, this matches participants who are either:

• in the participant group and aged between 18 and 30
• in the previous study allowlist and have an approval rate of at least 95

1
{
2
  "filter_id": "or",
3
  "selected_filters": [
4
    {
5
      "filter_id": "and",
6
      "selected_filters": [
7
        {
8
          "filter_id": "participant_group_allowlist",
9
          "selected_values": ["<participant_group_id>"]
10
        },
11
        {
12
          "filter_id": "age",
13
          "selected_range": {
14
            "lower": 18,
15
            "upper": 30
16
          }
17
        }
18
      ]
19
    },
20
    {
21
      "filter_id": "and",
22
      "selected_filters": [
23
        {
24
          "filter_id": "previous_studies_allowlist",
25
          "selected_values": ["<previous_study_id>"]
26
        },
27
        {
28
          "filter_id": "approval_rate",
29
          "selected_range": {
30
            "lower": 95
31
          }
32
        }
33
      ]
34
    }
35
  ]
36
}

Saved filter sets

Compound and / or groups like the examples above can be saved as a filter set and reused across studies. See Filter Sets for how to create, version, and apply them.

Limitations

Compound and / or filter groups are not currently supported for Quota or Representative Sample study types.