Groups
A group is a label on participants — an arm, a cohort, a stratum. Stages can be made available only to certain groups, automatic messages can target a group, and staff can be restricted to a group with group permissions (group.*). A participant can be in any number of groups.
Creating, renaming and deleting groups needs trial.admin. Reading them needs trial.read (a group-restricted account sees only its groups). Changing membership needs trial.write or trial.tagParticipants.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/trials/<trialId>/groups |
The trial's groups, as {"groups": [...]}. |
POST |
/trials/<trialId>/groups |
Create a group. |
PUT |
/groups/<groupId> |
Rename or recolour a group, or set or remove its automatic membership rule. |
DELETE |
/groups/<groupId> |
Delete a group. Participants lose the membership; nothing else changes. |
PUT |
/groups/<groupId>/memberships/<participantId> |
Add a participant to the group. Returns the participant's updated groups and arm. |
DELETE |
/groups/<groupId>/memberships/<participantId> |
Remove a participant from the group. |
Group fields
| Field | Type | Notes |
|---|---|---|
name |
string | 2–100 characters. |
colour |
string | A colour name or hex value, shown as the group's badge. |
membershipRule |
object or null | Automatic membership. type says what puts a participant in the group. "allStagesComplete" and "anyStageComplete" follow the participant's progress (complete, and started) and take nothing else: {"type": "allStagesComplete"}. A group with one of these can't be in a stage's availableToGroups, and vice versa. "stageCompleted" is a response to a stage: {"type": "stageCompleted", "stage": "<stageId>", "stageRecurrence": 3}, where stageRecurrence names an occurrence of a repeating or anchor-scheduled stage (counting from 0) or is null for any. "response" is an answer on a form: {"type": "response", "stage": "<stageId>", "condition": {"dataType": "<dataTypeId>", "operator": "exists" \| "equal" \| "notequal" \| "more" \| "less", "value": ..., "statement": "<likert statement key>"}}. condition has the same shape and meaning as a stage field's condition; the field must be on the stage, and a choice value must be one of its options. A participant joins while any of their responses to the stage meets it, and leaves when none does, but only from a group the rule put them in. null removes the rule and leaves its members in the group. |
A participant's autoGroups lists the groups a rule put them in. Adding or removing them by hand takes the group out of that list.
Study arms
A group marked isArm is a study arm. A participant's arm is held apart from their other groups: it is their arm, never in groups, and a participant has at most one. You put someone in an arm, or take them out of it, with the memberships endpoints above, by randomising them, or by listing the arm in groups when creating or bulk-updating participants. A groups list that leaves the arm out leaves it as it is, and naming a second arm is refused: take them out of the first. A randomised participant's arm can't be changed at all. In a study that conceals its allocation, arm is left out of every response for anyone without trial.readAllocation.
Membership in bulk
To put a participant in a group when registering them, pass groups on the participant in POST /trials/<trialId>/participants. To change many participants' groups at once, use PATCH /trials/<trialId>/participants with a groups list per participant, which replaces their membership. Both are in Participant management. To filter participants by group, use groupsInclude and groupsExclude on the participant list.