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
- Open your quest detail page
- Click Manage Participants in the action bar
- The participants page opens at
/quest/<guid>/participants
Only quest editors (the quest creator, organization members with quest.update permission, or listed collaborators) can access the participants page.
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. |
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"
}
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": "..." } |
Next Steps
