Filters Overview

Filters allow you to restrict access to your study based on participant demographics and attributes.

You can save combinations of filters, known as filter sets, to re-use across studies. These are useful if you’re running multiple studies with the same audience filters.

There are two types of filters:

• A select type filter allows you to select one or more options from a list of pre-defined choices.
• A range type filter allows you to select an upper and / or a lower bound for a given participant attribute.

To understand which filters are available to use, perform a GET request to the filters list endpoint. For each filter a type and a data_type attribute will be returned.

To use filters in a filter set, create a filter set with the correct filters selected, then apply it to your study using the filter_set_id parameter.

To use filters directly on a study, apply the filters using the filters parameter directly in the study creation endpoint.

For example, if you wanted to recruit using the ‘handedness’ filter, you would see a filter in the filters GET request which looks like this:

1
{
2
  "filter_id": "handedness",
3
  "title": "Handedness",
4
  "description": "",
5
  "question": "Are you left or right handed?",
6
  "type": "select",
7
  "data_type": "ChoiceID",
8
  "choices": {
9
      "0": "Left",
10
      "1": "Right",
11
      "2": "Ambidextrous",
12
    },
13
}

To apply this filter to a filter set or a study, your payload would look like this:

1
{
2
  "filter_id": "handedness",
3
  "selected_values": ["0", "1"],
4
}

This would result in your study recruiting from all participants who answered that they are either left or right-handed, and would exclude those who answered that they were ambidextrous.

Alternatively, if you wished to recruit using an age range filter, you would see this in your GET response:

1
{
2
  "filter_id": "age",
3
  "title": "Age",
4
  "description": "Participants were asked their date of birth. Please specify a current age range between min and max.",
5
  "question": "What is your date of birth?",
6
  "type": "range",
7
  "data_type": "integer",
8
  "min": 18,
9
  "max": 100,
10
}

To apply this filter to a filter set or a study, your payload would look like this:

1
{
2
  "filter_id": "age",
3
  "selected_range": {
4
    "lower": 18,
5
    "upper": 50,
6
  }
7
}

This would result in your study recruiting from all participants who at the time of publish were between 18 and 50 years old, inclusive.

It is not necessary to always provide both a lower and upper bound on a range filter. For example, if you simply wished to recruit all participants over the age of 50, you could set this filter as follows:

1
{
2
  "filter_id": "age",
3
  "selected_range": {
4
    "lower": 50,
5
  }
6
}