# 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](/api-reference/filters/get-filters).
For each filter a `type` and a `data_type` attribute will be returned.

```mermaid
%%{init: {
  "theme": "base",
  "flowchart": {
    "htmlLabels": true,
    "curve": "stepAfter"
  },
  "themeVariables": {
    "primaryColor": "#fafafa",
    "primaryBorderColor": "#e7e7ea",
    "primaryTextColor": "#0f2ac9",
    "fontFamily": "Inter, system-ui, sans-serif",
    "fontSize": "15px",
    "lineColor": "#bfc1c7",
    "lineWidth": 2,
    "defaultLinkColor": "#0f2ac9"
  },
  "themeCSS": ".node.finish a, .node.start a { color: currentColor !important; }"
}}%%
flowchart TD

    A["List the <a href="/api-reference/filters/get-filters">filters</a>"]:::start
    B["Find the pre-screener or filter set to use"]:::note

    C{"What is the <a href="/api-reference/filters/get-filters#response.body.results.type">type</a> of the pre-screener?"}:::decision
    F{"What is the <a href="/api-reference/filters/get-filters#response.body.results.data_type">data type</a> of the pre-screener?"}:::decision

    I["<a href="/api-reference/filters/get-filters#response.body.results.choices">Choices</a> of this pre-screener are in the response"]:::note

    J["Provide the <a href="/api-reference/studies/create-study#request.body.filters.filter_id">filter_id</a> and the IDs of your <a href="/api-reference/studies/create-study#request.body.filters.selected_values">selected values</a>"]:::finish

    K["Provide the <a href="/api-reference/studies/create-study#request.body.filters.filter_id">filter_id</a> and the <a href="/api-reference/studies/create-study#request.body.filters.selected_values">selected values</a> as described by the <a href="/api-reference/filters/get-filters#response.body.results.data_type">data type</a>"]:::finish

    L["<a href="/api-reference/filters/get-filters#response.body.results.min">Minimum</a> and <a href="/api-reference/filters/get-filters#response.body.results.max">maximum</a> values are inclusive"]:::note

    M["Provide the <a href="/api-reference/studies/create-study#request.body.filters.filter_id">filter_id</a> and <a href="/api-reference/studies/create-study#request.body.filters.selected_range">selected_range</a>, containing the inclusive <a href="/api-reference/studies/create-study#request.body.filters.selected_range.lower">lower</a> and <a href="/api-reference/studies/create-study#request.body.filters.selected_range.upper">upper</a> bounds"]:::finish

    A --> B --> C
    C -- "<span>&nbsp;&nbsp;<b>Select</b>&nbsp;&nbsp;</span>" --> F
    C -- "<span>&nbsp;&nbsp;<b>Range</b>&nbsp;&nbsp;</span>" --> L --> M
    F -- "<span>&nbsp;&nbsp;<b>Choice ID</b>&nbsp;&nbsp;</span>" --> I --> J
    F -- "<span>&nbsp;&nbsp;<b>Other</b>&nbsp;&nbsp;</span>" --> K

    classDef start fill:#0f2ac9,color:#ffffff,stroke:#0f2ac9,stroke-width:4px;
    classDef decision stroke:#bfc1c7,color:#4b5563,stroke-width:4px;
    classDef note stroke:#e7e7ea,color:#4b5563,stroke-width:4px,stroke-dasharray:4;
    classDef finish fill:#0f2ac9,color:#ffffff,stroke:#0f2ac9,stroke-width:4px;
```

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](/api-reference/studies/post-studies).

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:

```json
{
  "filter_id": "handedness",
  "title": "Handedness",
  "description": "",
  "question": "Are you left or right handed?",
  "type": "select",
  "data_type": "ChoiceID",
  "choices": {
      "0": "Left",
      "1": "Right",
      "2": "Ambidextrous",
    },
}
```

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

```json
{
  "filter_id": "handedness",
  "selected_values": ["0", "1"],
}
```

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:

```json
{
  "filter_id": "age",
  "title": "Age",
  "description": "Participants were asked their date of birth. Please specify a current age range between min and max.",
  "question": "What is your date of birth?",
  "type": "range",
  "data_type": "integer",
  "min": 18,
  "max": 100,
}
```

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

```json
{
  "filter_id": "age",
  "selected_range": {
    "lower": 18,
    "upper": 50,
  }
}
```

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:

```json
{
  "filter_id": "age",
  "selected_range": {
    "lower": 50,
  }
}
```