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.
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.
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.

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.