# Users

> Users are platform-wide accounts, so the API works on the members of your team. Find them by email or by your own external id, create learners, update their custom fields and groups, and deactivate or remove them. Administrators and people in other teams are protected.

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

| Method | Path | What it does |
|---|---|---|
| GET | `/users` | List and search members of the team |
| GET | `/users/{id}` | One user |
| POST | `/users` | Create a learner, or add an existing account to the team |
| PATCH | `/users/{id}` | Update a user |
| POST | `/users/{id}/deactivate` | Stop the user signing in to this team |
| POST | `/users/{id}/reactivate` | Let them sign in again |
| DELETE | `/users/{id}` | Remove the user from the team |
| GET | `/custom-fields` | Your team's custom field definitions (`users:read`) |

A person has one Continuum account, which can belong to several teams. The API only ever sees and changes **members of your team**: anyone else returns `404`.

## The user object

```json
{
  "id": 2,
  "email": "sam@example.org",
  "name": "Sam Patel",
  "locale": "en",
  "status": "active",
  "external": { "id": "M-1042", "source": "acme", "membership_status": null },
  "roles": ["learner"],
  "group_ids": [3, 9],
  "custom_fields": [
    { "field_id": 17, "name": "Membership number", "type": "text", "value": "M-1042", "option_id": null, "text": null },
    { "field_id": 18, "name": "Region", "type": "select", "value": "Wales", "option_id": 52, "text": null }
  ],
  "custom_fields_complete": true,
  "email_verified": true,
  "last_active_at": "2026-11-08T19:22:04+00:00",
  "created_at": "2026-02-11T10:00:00+00:00",
  "updated_at": "2026-11-09T14:05:51+00:00"
}
```

| Field | Description |
|---|---|
| `locale` | The user's language, such as `en` or `cy`, or `null`. |
| `status` | `active`, or `deactivated` (a member with no roles in this team, who can't sign in to it). |
| `external` | The user's id in your own system. See [External ids](#external-ids). `membership_status` is set by membership-system webhooks. |
| `roles` | Roles in this team only: `learner`, `author`, `admin`, `billing`, `presenter`, `owner` or `outreach_admin`. |
| `group_ids` | This team's groups the user is in. |
| `custom_fields` | Answers to your team's sign-up fields. For select, radio and checkbox fields, `value` is the option's label and `option_id` its id; `text` holds any "other" text. |
| `custom_fields_complete` | `false` when a required field is unanswered. The learner is asked to complete it when they next sign in. |
| `last_active_at` | Last activity in this team. |

## List and find users

| Query parameter | Description |
|---|---|
| `email` | Exact email address (not case-sensitive). |
| `external_id` | Your own id for the user. Searches your team's source unless you pass `external_source`. |
| `external_source` | The source to search, for example `wordpress:58`. |
| `group_id` | Members of one group. |
| `role` | Users with a role, such as `learner`. |
| `status` | `active` or `deactivated`. |
| `updated_since` | ISO 8601. Users whose account changed since then (see [Pagination](https://continuumlearn.com/developers/pagination#incremental-syncs)). |
| `limit`, `cursor` | See [Pagination](https://continuumlearn.com/developers/pagination). |

```bash
curl "https://your-team.continuumlearn.com/api/v2/users?external_id=M-1042" \
  -H "Authorization: Bearer $CONTINUUM_API_KEY"
```

## Create a user

`POST /users` creates a learner. The team's "approve new registrations" setting is skipped, because the key acts as an administrator.

| Body field | Required | Description |
|---|---|---|
| `email` | Yes | The email address. |
| `name` | Yes | Full name. |
| `locale` | No | One of the team's enabled languages. Defaults to the team's default language. |
| `external_id` | No | Your own id for the user (string). |
| `external_source` | No | Leave out, or set to your team's own source. |
| `group_ids` | No | Up to 100 of the team's groups. Groups managed by auto-assign rules can't be used. |
| `custom_fields` | No | Up to 50 answers, as `{"field_id": value}`. See [Custom fields](#custom-fields). |
| `notify` | No | Default `true`. See below. |

```bash
curl https://your-team.continuumlearn.com/api/v2/users \
  -H "Authorization: Bearer $CONTINUUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-M-1042" \
  -d '{
    "email": "ali@example.org",
    "name": "Ali Khan",
    "external_id": "M-1042",
    "group_ids": [3],
    "custom_fields": { "17": "M-1042", "18": 52 },
    "notify": true
  }'
```

What happens depends on the email address:

| The email | Result |
|---|---|
| Is new to Continuum | A new account is created with the learner role. Returns `201` with the user. With `notify: true` the person gets the verification email, with a temporary password. With `notify: false` no email is sent and the address is marked as verified: use this when they will sign in through single sign-on or a [sign-in link](https://continuumlearn.com/developers/sign-in-links). |
| Already belongs to a member of this team | `409` `user_exists`, with `details.user_id`. Update them with `PATCH` instead. |
| Has a Continuum account in another team | The existing account is added to your team as a learner, and its name and language are left alone. Returns `202` with only `{"data": {"id", "email", "status": "attached"}}`; fetch the user afterwards. With `notify: true` they get the "you've been added to a team" email. The user is then [protected](#protected-users), because the account is shared. Sending `external_id` in this case returns `409` `user_protected` and nothing is changed. |

Required custom fields are not enforced when you create a user: check `custom_fields_complete` in the response.

## Update a user

`PATCH /users/{id}` changes only the fields you send.

| Body field | Description |
|---|---|
| `name`, `locale` | Not for protected users. |
| `external_id`, `external_source` | Set or change the user's external id. `"external_id": null` removes it. Not for protected users. |
| `group_ids` | Replaces the user's membership of the team's manual groups. Groups managed by rules aren't affected. |
| `custom_fields` | `{"field_id": value}`. `null` clears an answer. |

Email addresses and passwords can't be changed through the API.

## Deactivate, reactivate and remove

- **`POST /users/{id}/deactivate`** removes the user's roles in this team, so they can no longer sign in to it. Their membership, enrolments, progress and certificates stay. Safe to repeat.
- **`POST /users/{id}/reactivate`** gives them the learner role again (and the presenter role, if they are linked to a presenter profile). Other roles removed by a deactivation are not restored. Safe to repeat.
- **`DELETE /users/{id}`** removes the user from the team and its groups, and returns `204`. Their account (and any other teams they belong to) is untouched, and their enrolment and progress records are kept.

All three refuse protected users, and deactivating or removing a linked presenter also returns `409` `user_protected`: unlink the presenter profile in **Manage > People > Presenters** first.

## Protected users

Some accounts can't be changed through the API beyond team-local data, so an integration can never lock out an administrator or rewrite someone else's account. A user is protected when they:

- hold the admin, owner, billing, author or outreach administrator role in this team, or own the team;
- are Continuum platform staff;
- belong to any other Continuum team.

For protected users, the API can still change custom field answers and group membership. Changing name or language, writing an external id, deactivating or removing them returns `409` `user_protected`.

## External ids

`external` links a user to the record in your own system, such as a membership number, so you can find them without storing Continuum ids.

- Each account has **one** external id slot.
- Your API key writes in your team's own **source**, which is your team's short name (for example `acme`). You don't need to send `external_source` at all.
- Ids written by other routes are read-only through the API: `wordpress:{team id}` from the WordPress plugin, `bama` from an older single sign-on. A user who already has one of those returns `409` `external_identity_locked` if you try to write yours.
- An external id can only belong to one member of the team: a duplicate returns `409` `external_id_taken`.
- Membership-system webhooks use the same source, so ids written by the API and by your membership system's webhooks match up.

## Custom fields

`custom_fields` takes your team's sign-up fields by id. `GET /custom-fields` lists them all, with their option ids, in the order the sign-up form shows them (not paginated):

```bash
curl https://your-team.continuumlearn.com/api/v2/custom-fields \
  -H "Authorization: Bearer $CONTINUUM_API_KEY"
```

```json
{
  "data": [
    { "id": 17, "name": "Membership number", "type": "text", "required": true, "options": null },
    {
      "id": 18,
      "name": "Region",
      "type": "select",
      "required": false,
      "options": [
        { "id": 51, "label": "England", "specify": false },
        { "id": 52, "label": "Wales", "specify": false },
        { "id": 53, "label": "Other", "specify": true }
      ],
      "translations": { "cy": "Rhanbarth" }
    }
  ]
}
```

`type` is `text`, `textarea`, `email`, `tel`, `number`, `date`, `select`, `radio` or `checkbox`. `options` is `null` for the free-text types. An option with `specify: true` is a "please specify" option that takes extra text. `translations` (only present when the field name has been translated) maps a language code to the translated name.

| Field type | Value to send |
|---|---|
| Text, text area, email, phone | A string of at most 1,000 characters. |
| Number | A number, 0 or more. |
| Date | A string in `YYYY-MM-DD` format. |
| Select, radio | The option's id, or `{"option_id": 53, "text": "the specified text"}` for a `specify` option. |
| Checkbox | A single option id. Several values aren't supported yet. |

An option from a different field, an unknown field id or a badly formatted value returns `422` `validation_error`, with the field named in `details` (for example `custom_fields.17`). Saving custom fields also runs your team's group auto-assign rules, exactly as when the learner fills them in.

## Frequently asked questions

### How do I avoid creating duplicates?

Look the person up first with `GET /users?email=` or `?external_id=`, and send an `Idempotency-Key` with each `POST /users` so a retry can't create the user twice. A second create for a member's email returns `409` `user_exists` with their id anyway.

### Does deleting a user delete their account?

No. It removes them from your team only. The account, and their membership of any other teams, stays.

### Can the API make someone an administrator?

No. The API only ever gives the learner role (and the presenter role to linked presenters). Change roles in **Manage > People**.
