# Enrolments

> PUT /users/{user}/enrolments/{course} enrols a user (201 new, 200 already enrolled, 202 waitlisted). POST /enrolments does the same with the user identified by email or external id. API enrolment takes no payment and skips approval, but respects capacity unless you say otherwise.

Reads need `enrolments:read`; writes need `enrolments:write`.

| Method | Path | What it does |
|---|---|---|
| PUT | `/users/{user}/enrolments/{course}` | Enrol a user on a course |
| POST | `/enrolments` | Enrol, identifying the user by id, email or external id |
| DELETE | `/users/{user}/enrolments/{course}` | Remove a direct enrolment |
| GET | `/users/{user}/enrolments/{course}` | One user's enrolment on one course |
| GET | `/users/{user}/enrolments` | A user's enrolments |
| GET | `/courses/{course}/enrolments` | A course's enrolments |

## What "enrolled" means

A user is enrolled on a course when they have a **direct** enrolment, or they are in a group assigned to the course as `auto` (see [Groups](https://continuumlearn.com/developers/groups)). A group assigned as `optional` only offers the course; it shows in `offered_via_group_ids`, not in `sources`.

## The enrolment object

```json
{
  "user_id": 2,
  "course_id": 412,
  "status": "enrolled",
  "enrolled_at": "2026-11-09T14:05:51+00:00",
  "unenrolled_at": null,
  "sources": [
    { "type": "direct", "enrolled_at": "2026-11-09T14:05:51+00:00" },
    { "type": "group", "group_id": 9, "assignment": "auto" }
  ],
  "offered_via_group_ids": [],
  "request": null
}
```

| Field | Description |
|---|---|
| `status` | `enrolled`, `pending_approval` (waiting for an administrator), `waitlisted` (on the waiting list), `unenrolled` (was directly enrolled, then removed) or `not_enrolled`. |
| `enrolled_at` | When the direct enrolment was made, or `null` if they are only enrolled through a group. |
| `sources` | Every way the user is enrolled: `direct`, and/or each `group`. |
| `request` | The latest sign-up request for the course (`status` and `created_at`), or `null`. |

Lists by course also include a compact `user` on each row: `{id, email, name, external: {id, source}}`, where `external.id` and `external.source` are strings, or `null` when the user has no external id. Webhook events use the same shape.

## Enrol a user

```bash
curl -X PUT https://your-team.continuumlearn.com/api/v2/users/2/enrolments/412 \
  -H "Authorization: Bearer $CONTINUUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notify": false}'
```

| Response | Meaning |
|---|---|
| `201` | A new enrolment was created. |
| `200` | The user was already enrolled (directly or through a group). Nothing changed. |
| `202` | The course is full and you sent `waitlist: true`: the user is on the waiting list (`status: waitlisted`). |

| Body field | Default | Description |
|---|---|---|
| `notify` | `true` | Send the "you have been enrolled" email. Publications never send it. Pass `false` for bulk syncs. |
| `waitlist` | `false` | When the course is full, add the user to the waiting list (`202`) instead of failing. |
| `ignore_capacity` | `false` | Enrol even if the course is full. |
| `check_prerequisites` | `false` | Refuse with `422` `prerequisites_unmet` if the user hasn't completed the course's prerequisites. This includes learning-path order: for a user on an "In order" programme, the unfinished required course before this one counts as an unmet prerequisite. Without the flag the path order is ignored, as an administrator's enrolment would. |

Calling `PUT` again is safe: one enrolment, whatever the number of calls.

Enrolling through the API acts like an administrator:

- **No payment is taken.** Paid courses are enrolled without an order. Charge through your own system, or send learners to the course's `buy_url` instead.
- **Approval is skipped.** On a course that needs approval the user is enrolled straight away, and any open sign-up request is marked approved.
- **Prerequisites are not checked** unless you send `check_prerequisites: true`.
- **Capacity is enforced.** A full course returns `409` `course_full`, unless you send `waitlist` or `ignore_capacity`.
- **Staff can be enrolled too.** A linked presenter or administrator who previews a course is in "observer mode" and records no completions. Enrolling them ends that, and their activity then counts like a learner's.

## Enrol by email or external id

`POST /enrolments` behaves exactly like the `PUT`, but finds the user for you. Send `course_id` and exactly one of `user_id`, `email` or `external_id` (with `external_source` if it isn't your team's). Only members of the team are matched; anyone else returns `404`.

```bash
curl https://your-team.continuumlearn.com/api/v2/enrolments \
  -H "Authorization: Bearer $CONTINUUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: enrol-M-1042-412" \
  -d '{"course_id": 412, "external_id": "M-1042", "notify": false}'
```

```php
<?php
$res = $client->post('enrolments', [
    'headers' => ['Idempotency-Key' => "enrol-{$memberId}-{$courseId}"],
    'json' => ['course_id' => $courseId, 'external_id' => $memberId, 'notify' => false],
    'http_errors' => false,
]);

switch ($res->getStatusCode()) {
    case 200: case 201: break; // enrolled
    case 202: error_log("Waitlisted {$memberId}"); break;
    case 404: error_log("{$memberId} isn't in the team yet: create them first"); break;
    case 409: error_log(json_decode($res->getBody(), true)['error']['code']); break; // e.g. course_full
    default: throw new RuntimeException((string) $res->getBody());
}
```

```js
const res = await fetch('https://your-team.continuumlearn.com/api/v2/enrolments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CONTINUUM_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `enrol-${memberId}-${courseId}`,
  },
  body: JSON.stringify({ course_id: courseId, external_id: memberId, notify: false }),
});
if (res.status === 409) console.warn((await res.json()).error.code); // e.g. course_full
```

## Remove an enrolment

`DELETE /users/{user}/enrolments/{course}` removes the direct enrolment and clears any pending or waiting request. It returns `200` with the enrolment, whether or not there was anything to remove. The user's progress records are kept.

If the course is **required training** for that user, the request is refused with `409` and `error.code` `required_training`, and nothing changes. An active training requirement keeps its learners enrolled: exempt the learner or take them out of the requirement's audience (in **Manage > Compliance**) first, then retry. The same refusal applies to removal by the learner and by administrators in Manage. See [errors](https://continuumlearn.com/developers/errors).

If the user is still in a group assigned to the course as `auto`, they stay enrolled: the response has `status: enrolled` with that group in `sources`. Take them out of the group to end it.

## List enrolments

`GET /users/{user}/enrolments` and `GET /courses/{course}/enrolments` are cursor-paginated (see [Pagination](https://continuumlearn.com/developers/pagination)).

| Query parameter | Description |
|---|---|
| `status` | `enrolled` (the default), `pending_approval`, `waitlisted` or `unenrolled`. |
| `include_unenrolled` | `true` to include people who were enrolled and then removed. |
| `enrolled_since` | Course list only. ISO 8601: direct enrolments created since then. Learners enrolled only through a group have no enrolment date, so this filter leaves them out. |

`GET /users/{user}/enrolments/{course}` returns `200` with `status: not_enrolled` when there is no enrolment, rather than a `404`.

## Frequently asked questions

### Can I enrol someone on a bundle or programme?

Not through the API yet: enrolments are per course. Enrol them on each course, or assign a group to the courses.

### Will the learner get an email?

Only if `notify` is `true` (the default) and the course isn't a publication. Bulk imports should pass `notify: false`.
