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

# Managing Participants

> View, filter, and manage participant status and cohort assignments for your quest.

Every quest has a **Participants** page where researchers can view enrolled participants, update their lifecycle status, and assign them to cohorts. This is the primary operational surface for managing a study's participant roster.

## Accessing the Participants Page

1. Open your quest detail page
2. Click **Manage Participants** in the action bar
3. The participants page opens at `/quest/<guid>/participants`

<Info>
  Only quest editors (the quest creator, organization members with `quest.update` permission, or listed collaborators) can access the participants page.
</Info>

## The Participant Table

The participants table shows every person who has joined the quest. Each row includes:

| Column                 | Description                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| **Participant**        | Username, email, or public key — whichever is available. A secondary identifier is shown below. |
| **Cohort**             | The cohort the participant belongs to, or "Unassigned". Editable via dropdown.                  |
| **Status**             | The participant's current lifecycle status, shown as a colored badge. Editable via dropdown.    |
| **Joined**             | When the participant joined the quest.                                                          |
| **Last status update** | When the status was last changed.                                                               |

Changes to status and cohort **save immediately** — there is no separate save button.

## Participant Statuses

Participants move through a lifecycle of statuses. Each status has a distinct color badge for quick visual identification:

| Status         | Color  | Description                                   |
| -------------- | ------ | --------------------------------------------- |
| **Screened**   | Gray   | Participant has been reviewed for eligibility |
| **Eligible**   | Cyan   | Meets eligibility criteria                    |
| **Ineligible** | Amber  | Does not meet eligibility criteria            |
| **Consented**  | Violet | Has provided informed consent                 |
| **Enrolled**   | Gray   | Joined the quest (default status on join)     |
| **Active**     | Blue   | Currently participating in the study          |
| **Completed**  | Green  | Finished all study activities                 |
| **Withdrawn**  | Red    | Withdrew from the study                       |
| **Excluded**   | Rose   | Removed from the study by the researcher      |

### Automatic Enrollment

When a participant joins a quest, they are automatically created as a **QuestSubject** with `enrolled` status. No manual action is needed — the participant appears in the table as soon as they complete the join flow.

### Changing Status

Select a new status from the dropdown in the Status column. The update is sent to the server immediately. Use this to track participant progress through your study protocol — for example, moving participants from `enrolled` → `active` → `completed`.

## Cohorts

Cohorts let you organize participants into groups — useful for multi-arm studies, A/B conditions, treatment vs. control groups, or any grouping your study design requires.

### Creating Cohorts

Cohorts are created via the API:

```
POST /api/quest/:questGuid/cohorts
{
  "name": "Treatment Group A",
  "description": "Participants receiving the active intervention"
}
```

Each cohort has a **name** (required) and an optional **description**.

### Assigning Participants to Cohorts

In the participants table, use the Cohort dropdown to assign or reassign a participant. Select "Unassigned" to remove the cohort assignment. Changes save immediately.

## Filtering

The participants page includes two filters above the table:

* **Filter by status** — show only participants with a specific status (e.g., only "Active" participants)
* **Filter by cohort** — show only participants in a specific cohort, or those who are "Unassigned"

Filters can be combined — for example, show all "Active" participants in "Treatment Group A".

## Refreshing Data

Click **Refresh participants** to reload the participant list from the server. This is useful when participants are actively joining and you want to see the latest roster.

## API Reference

All participant operations are available via the REST API for programmatic access:

| Method  | Endpoint                                             | Description                                                                                                                           |
| ------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`   | `/api/quest/:questGuid/subjects`                     | List all participants. Supports `?status=` and `?cohortGuid=` query filters. Use `cohortGuid=unassigned` for unassigned participants. |
| `PATCH` | `/api/quest/:questGuid/subjects/:subjectGuid/status` | Update a participant's status. Body: `{ "status": "active" }`                                                                         |
| `PATCH` | `/api/quest/:questGuid/subjects/:subjectGuid/cohort` | Assign a participant to a cohort. Body: `{ "cohortGuid": "..." }` or `{ "cohortGuid": null }` to unassign.                            |
| `GET`   | `/api/quest/:questGuid/cohorts`                      | List all cohorts for a quest.                                                                                                         |
| `POST`  | `/api/quest/:questGuid/cohorts`                      | Create a new cohort. Body: `{ "name": "...", "description": "..." }`                                                                  |

All endpoints require authentication and editor-level access to the quest.

## Next Steps

<CardGroup cols={2}>
  <Card title="Participant Journey" icon="route" href="/quests/participant-journey">
    Understand the end-to-end flow from a participant's perspective.
  </Card>

  <Card title="Running a Study" icon="microscope" href="/quests/running-a-study">
    Full lifecycle guide for conducting research with NeuroFusion.
  </Card>

  <Card title="Viewing Quest Data" icon="chart-bar" href="/quests/viewing-quest-data">
    Explore collected datasets, responses, and health metrics.
  </Card>

  <Card title="Data Audit Trail" icon="shield-check" href="/data/audit-trail">
    Review who accessed or modified study data.
  </Card>
</CardGroup>