> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Screening respondents

> How to add, update, and preserve panel and custom screener questions on a study — including the replacement gotcha and what not to add.

Screener questions filter who can participate in a study. The platform supports
two kinds of screener, and they coexist on the same study.

## Two kinds of screener question

### Panel questions

Panel questions target the panel and map to a canonical qualification in
the panel catalog.

Required fields:

* `is_panel_question: true`
* `qualification_id` — sourced from `list_available_panel_questions`

### Custom questions

Custom screeners are free-form questions you write yourself. They apply to any
participant regardless of panel affiliation.

Required fields:

* `is_panel_question: false`
* Your own question text

No `qualification_id` is needed. Custom questions can capture any criteria the
panel catalog does not cover.

## The panel question catalog

Before adding panel screeners, call `list_available_panel_questions` to browse the
canonical list. This gives you the correct `qualification_id` values and the
expected answer options for each question. Using an invalid `qualification_id`
will cause the panel survey to fail at launch.

## The replacement gotcha

`update_study` with a `screener_questions` payload **replaces the entire list**.
It does not append or merge.

Safe update pattern:

1. Call `get_study` to fetch the current study record.
2. Copy the `screener_questions` array from the response.
3. Add or remove questions in that array.
4. Pass the modified array back in `update_study`.

Skipping step 1 silently drops all existing screeners. This is the most common
screener-related mistake.

## What not to add

**No consent questions.** Never add questions like:

* "Do you consent to being recorded?"
* "Are you willing to participate?"

Consent is collected by the platform outside the screener flow. Adding these
questions creates a duplicate consent step that confuses participants and may
invalidate the consent record.

**No auto-generated screeners on create.** When calling `create_study`, do not
automatically generate screener questions. Create the study without screeners and
only add them in a subsequent `update_study` call when the user explicitly
asks for screening.