# Finding the right participants

# Finding the right participants

This guide demonstrates how to find and select the right participants for your studies using Prolific's API.

## Pre-screeners

Pre-screeners (also called Filters) allow you to restrict access to your study based on a wide variety of criteria. This guide will demonstrate how to select and use pre-screeners via API.

For more information on the types of screeners we have, please read the help center article [here](https://researcher-help.prolific.com/en/article/filters).

```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;
```

<Steps>
  <Step>
    Get the list of pre-screeners

    <RunnableEndpoint endpoint="GET /api/v1/filters/" readonly={["examples"]} />

    There are 2 types of pre-screeners:

    * `select`: select from one of more options from a list of pre-defined choices e.g., first language
    * `range`: specify an upper and/or a lower bound e.g., age
  </Step>

  <Step>
    When creating a study, specify a list of pre-screeners

    <RunnableEndpoint endpoint="POST /api/v1/studies/" example="study_with_select_filters" readonly={["examples"]} />
  </Step>

  <Step>
    <Note>
      This is an optional step.
    </Note>

    You can save combinations of pre-screeners as screener sets, to reuse across studies. These are useful if you're
    running multiple studies with the same audience criteria.

    <RunnableEndpoint endpoint="POST /api/v1/filter-sets/" readonly={["examples"]} />
  </Step>
</Steps>

## In-study screening

Custom screening lets you check for participant characteristics that aren't available in our built-in pre-screening options. This guide will demonstrate how to create and manage in-study screening via API.

For more detail on custom screening, including a video demo, see the [help center article](https://researcher-help.prolific.com/en/article/custom-screening).

<Steps>
  <Step>
    Create the survey with pre-screening questions. Set up the survey to take different paths, for example:

    * If someone answers "Yes" they'll continue to your main survey
    * If it's a "No" they'll be directed to your end of survey message

    When participants are screened out, the survey must redirect them to Prolific with the appropriate completion code
    (or provide them with the code to enter manually).

    Check out our [integration guides](https://researcher-help.prolific.com/en/article/integration-guides) for how to
    set up these paths, including how to create your end of survey message in your software.
  </Step>

  <Step>
    Create a custom screening study on Prolific, with a screened out completion path

    <RunnableEndpoint endpoint="POST /api/v1/studies/" example="study_with_custom_screening" readonly={["examples"]} />

    **Screen-out slots**: The maximum number of participants that can be screened out. This is separate from your
    study's total number of places. Once the maximum screen-out slots are filled, your study automatically pauses.

    **Screen-out reward amount**: The fixed payment for screened-out participants (minimum £0.10/\$0.14). This must be
    less than the study reward and cannot be changed after publishing your study.
  </Step>

  <Step>
    Publish the study

    <RunnableEndpoint endpoint="POST /api/v1/studies/{id}/transition/" example="publish_study" readonly={["examples"]} />

    When participants return to Prolific with a screened out completion code, the submission status is set to
    `SCREENED_OUT` and they are automatically paid the screen out reward specified.
  </Step>
</Steps>

## Find specialist and domain experts

Prolific creates and manages custom participant groups of specially curated experts, e.g., STEM experts and Language specialists. [Click here](https://researcher-help.prolific.com/en/article/domain-experts) to understand what domain experts are available and how they are verified.

Follow these steps to recruit domain experts for your studies via API:

<Steps>
  <Step>
    Identify the custom group associated with the expert

    <RunnableEndpoint endpoint="GET /api/v1/filters/" example="Custom groups" readonly={["examples"]} />
  </Step>

  <Step>
    When creating a study, specify the pre-screening filter ID

    <RunnableEndpoint endpoint="POST /api/v1/studies/" example="study_with_custom_group" readonly={["examples"]} />
  </Step>

  <Step>
    Publish the study

    <RunnableEndpoint endpoint="POST /api/v1/studies/{id}/transition/" example="publish_study" readonly={["examples"]} />
  </Step>
</Steps>

## Dynamically manage participant eligibility

Within study setup, you can use a participant's **first submission as a decision point**, and automatically block them from re-entering your study if they ***don’t*** meet certain criteria or fail an attention check.

Here’s how to do it:

<Steps>
  <Step title="Create a Participant Group">
    Create a group where screened-out participants will be added. For more information on how to do this [Create a new
    participant group](/api-reference/participant-groups/create-participant-group).
    Save the `participant_group_id` – you’ll use this in the next step.

    <Frame caption="Screen in Researcher UI | Section: ‘Participants’">
      <img src="https://files.buildwithfern.com/prolific-beta.docs.buildwithfern.com/b612324e43278517c569c57e1b90586a7cc25af736b69b06dabab62b52c8ec77/docs/assets/screen.webp" alt="Participant Groups" />
    </Frame>
  </Step>

  <Step title="Set up your study to dynamically block future entries">
    Use a **completion code with an action** to add disqualified participants to the group, and **block that group from
    participating again**.

    <Note>
      Participants who use this completion code will be added to the participant group and automatically blocked from
      entering the study again.
    </Note>

    <Frame caption="Screen in Researcher UI | Section: ‘Add a completion path’">
      <img src="https://files.buildwithfern.com/prolific-beta.docs.buildwithfern.com/bec7d7293433ab1c9152282859061fa1cdfe8f8001c2e20c0d69555acdbde6ee/docs/assets/screen2.webp" alt="Add a completion path" />
    </Frame>

    <Frame caption="Screen in Researcher UI | Section: ‘Add Participant Group Screener A’">
      <img src="https://files.buildwithfern.com/prolific-beta.docs.buildwithfern.com/9d882efaa3dd3b736dd468acd271e18cd91abb9dd22b0dc3aac7327dd523c0be/docs/assets/screen3.webp" alt="Add Participant Group Screener A" />
    </Frame>

    <Frame caption="Screen in Researcher UI | Section: ‘Add Participant Group Screener B’">
      <img src="https://files.buildwithfern.com/prolific-beta.docs.buildwithfern.com/edadc4fdb7e4812dccf61cdf2ef5c0f27fb3db2224892573d2c797266eac85bd/docs/assets/screen4.webp" alt="Add Participant Group Screener B" />
    </Frame>

    In the request body, `completion_codes` should contain a code with an “ADD\_TO\_PARTICIPANT\_GROUP” action:

    ```json
    "completion_codes": [
    {
      "code": "GHIJKL",
      "code_type": "SCREENED_OUT",
      "actions": [
    {
      "action": "MANUALLY_REVIEW"
    },
    {
      "action": "ADD_TO_PARTICIPANT_GROUP",
      "participant_group": "<insert participant group ID>"
    }
      ]
    }
    ]

    ```

    And include this `completion_codes` filter in your study setup:

    ```json
    {
      "filter_id": "participant_group_blocklist",
      "selected_values": [
      "<insert participant group ID>"
      ]
    }

    ```

    ✨ **Result:** You now have an **adaptive eligibility flow**, letting you use early responses to control who
    continues — without needing to pause or reconfigure your study!
  </Step>
</Steps>