# Groups

> Groups collect learners, for example a membership grade or a cohort. Read them with users:read; create, change and delete them and their members with groups:write. Assigning a group to a course enrols every member and needs enrolments:write too.

| Method | Path | Scope | What it does |
|---|---|---|---|
| GET | `/groups` | `users:read` | List groups. Filter with `?reference=`. |
| GET | `/groups/{id}` | `users:read` | One group |
| POST | `/groups` | `groups:write` | Create a group |
| PATCH | `/groups/{id}` | `groups:write` | Update a group |
| DELETE | `/groups/{id}` | `groups:write` | Delete a group |
| GET | `/groups/{id}/members` | `users:read` | List members |
| PUT | `/groups/{id}/members/{user_id}` | `groups:write` | Add one member |
| DELETE | `/groups/{id}/members/{user_id}` | `groups:write` | Remove one member |
| POST | `/groups/{id}/members` | `groups:write` | Add and remove members in bulk |
| PUT | `/groups/{id}/courses/{course_id}` | `groups:write` + `enrolments:write` | Assign the group to a course |
| DELETE | `/groups/{id}/courses/{course_id}` | `groups:write` + `enrolments:write` | Remove the assignment |

## The group object

```json
{
  "id": 9,
  "name": "Members 2026",
  "reference": "members-2026",
  "locked": false,
  "auto_assign": { "enabled": false, "has_rules": false },
  "explore_assigned_only": false,
  "hide_enrollment": false,
  "member_count": 214,
  "created_at": "2026-01-05T09:00:00+00:00",
  "updated_at": "2026-11-09T14:05:51+00:00"
}
```

| Field | Description |
|---|---|
| `reference` | Your own reference for the group, unique in the team. Use it to find the group from your system. |
| `locked` | A locked group can't be renamed, given a new reference or deleted. |
| `auto_assign` | Whether the group fills itself from rules (set in Manage). When it does, members can't be added or removed by hand. |
| `explore_assigned_only` | "Restrict Explore to assigned courses": members' Explore page lists only the courses assigned to the group as optional, and hides public courses and events. |
| `hide_enrollment` | The group's "Hide Enrollment" setting in Manage. |

## Create and update

`POST /groups` takes `name` (required, unique among the team's groups, up to 255 characters), `reference`, `explore_assigned_only` and `hide_enrollment`, and returns `201`. `PATCH /groups/{id}` takes the same fields.

```bash
curl https://your-team.continuumlearn.com/api/v2/groups \
  -H "Authorization: Bearer $CONTINUUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: group-members-2026" \
  -d '{"name": "Members 2026", "reference": "members-2026"}'
```

Things to know:

- Group names can only use Western European (Latin-1) characters at present. Others return `422` `unsupported_characters`.
- A duplicate name or reference returns `422` `validation_error`.
- Auto-assign rules can't be set through the API. Set them in **Manage > People > Groups**.
- Groups whose reference starts with your team's short name are kept in step by your membership system's webhooks, which rewrite their members on every sync. Don't manage those groups through the API as well.

## Members

`PUT /groups/{id}/members/{user_id}` adds one member and `DELETE` removes one. Both are safe to repeat. The user must be a member of the team (`404` otherwise), and a group managed by auto-assign rules returns `409` `group_rules_managed`.

To change many members at once, `POST /groups/{id}/members` takes up to 100 ids in each list:

```bash
curl https://your-team.continuumlearn.com/api/v2/groups/9/members \
  -H "Authorization: Bearer $CONTINUUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"add": [2, 31, 47], "remove": [12]}'
```

```json
{ "data": { "added": [2, 31], "removed": [12], "not_found": [47] } }
```

`added` and `removed` list only the users whose membership actually changed. `not_found` lists ids that aren't members of the team. An id in both lists is removed.

`GET /groups/{id}/members` returns a compact user for each member (`id`, `email`, `name`, `status`, `external`). For the full user, use `GET /users?group_id={id}`.

## Assign a group to a course

`PUT /groups/{id}/courses/{course_id}` assigns the group to a course. It sends no emails.

| `assignment` | Effect |
|---|---|
| `auto` (default) | Every member of the group is enrolled on the course, including people who join the group later. |
| `optional` | The course is offered to members in Explore, but they aren't enrolled until they choose it. |

```bash
curl -X PUT https://your-team.continuumlearn.com/api/v2/groups/9/courses/412 \
  -H "Authorization: Bearer $CONTINUUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assignment": "auto"}'
```

Calling it again changes the assignment. `DELETE` removes the assignment and returns `204`. See [Enrolments](https://continuumlearn.com/developers/enrolments) for how group enrolment shows in a user's enrolment.

## Frequently asked questions

### What happens to members when I delete a group?

They are taken out of the group and the group is deleted. Their accounts, and any direct enrolments, are not affected. Enrolments that came only from the group's course assignments end with it.

### Can I add someone who isn't in my team yet?

Not directly. Create or attach them with `POST /users` (you can pass `group_ids` there), then manage their groups.
