---
title: "Invite a user to series and modules"
description: "Invites a user to one or more Mindtickle series or to specific modules within a series."
contentType: "api-reference"
url: "https://developer.mindtickle.com/docs/training/series/invite-a-user-to-series-and-modules/"
---

## Prerequisites

1. [Authentication and setup](/docs/getting-started/authentication-and-setup/): A valid access token.
2. [List all series](/docs/training/series/list-all-series/): The series you invite the user to must exist.

## Endpoint

```http
POST /services/data/v4.0/mtobjects/User
```

Base URL: the standard REST host for your region. See [Base URLs](/docs/getting-started/authentication-and-setup/#base-urls).

Headers: `Authorization: Bearer ACCESS_TOKEN`, `Content-Type: application/json`.

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Recommended | Name of the user. |
| `username` | string | Required if UID enabled | Unique identifier for the user. |
| `timezone` | string | Optional | [Time zone ID value](/docs/users-and-groups/users/time-zone-values/) for the time zone you want to configure for the user. |
| `id` | string | Optional | Mindtickle ID of the user. |
| `profile` | AttributeMap | Optional | Mindtickle profile fields information. |
| `profile.dp` | string | Optional | Mindtickle profile fields shortkey. |
| `profile.lang` | string | Optional | Sets the display language of the learning site for the user. Use a language code that the learning site supports. |
| `email` | string | Required if UID disabled | Email address of the user. Used for communication purposes, such as invitation and reminder emails from the platform, regardless of your instance's UID mode. |
| `groupIds` | Array[string] | Optional | IDs of the groups that you want to add the user to. |
| `seriesEntities` | Array[SeriesEntity] | Optional | Series and modules that you want to assign to the user. |
| `seriesEntities[].seriesId` | string | Required | ID of the series. |
| `seriesEntities[].entities` | Array[string] | Optional | List of specific module IDs within the series. |
| `source` | string | Read-only | Provisioning source. Values supplied in the request are ignored, as documented for the same endpoint in [Create a user](/docs/users-and-groups/users/create-a-user/#notes). |
| `managers` | Array[Manager] | Optional | List of managers to assign to the user. Each manager is identified by either `username` or `email`, depending on your instance's UID mode. |
| `managers[].username` | string | Required if UID enabled | Username of the manager. |
| `managers[].email` | string | Required if UID disabled | Email address of the manager. |
| `managers[].key` | string | Optional | Mindtickle relationship shortkey for the Manager attribute. |

### Request example

The identifier you provide depends on whether UID is enabled for your Mindtickle instance.

When UID is enabled, identify the user and each manager by `username`:

```json
{
  "name": "Alex Fry",
  "username": "alex.fry@example.com",
  "id": "123456789abcd101",
  "timezone": "America/Costa_Rica",
  "profile": {
    "dp": "abc",
    "lang": "Italian"
  },
  "groupIds": ["1234567890123456102"],
  "seriesEntities": [
    {
      "seriesId": "1234567890123456103",
      "entities": ["1234567890123456104", "1234567890123456105"]
    },
    {
      "seriesId": "1234567890123456106",
      "entities": []
    }
  ],
  "managers": [
    {
      "username": "james.smith@example.com",
      "key": "a_0"
    }
  ]
}
```

When UID is disabled, identify the user and each manager by `email`. The `username` field is not used and can be omitted:

```json
{
  "name": "Alex Fry",
  "email": "alex.fry@example.com",
  "id": "123456789abcd101",
  "timezone": "America/Costa_Rica",
  "profile": {
    "dp": "abc",
    "lang": "Italian"
  },
  "groupIds": ["1234567890123456102"],
  "seriesEntities": [
    {
      "seriesId": "1234567890123456103",
      "entities": ["1234567890123456104", "1234567890123456105"]
    },
    {
      "seriesId": "1234567890123456106",
      "entities": []
    }
  ],
  "managers": [
    {
      "email": "james.smith@example.com",
      "key": "a_0"
    }
  ]
}
```

## Response

| Field | Type | Description |
| --- | --- | --- |
| `requestId` | string or null | Request identifier. The response examples return `null`. |
| `responseCode` | integer | Special response codes from the server. |
| `responseType` | string | Type of response from the server. |
| `taskCompleted` | boolean | Flag for task completion. `true` means the task is successfully queued in Mindtickle. |
| `processIds` | Array[string] | Mindtickle process IDs. Use them to check the status of a request. |

### Response example

```json
{
  "requestId": null,
  "responseCode": 0,
  "responseType": "BULK_RESPONSE",
  "taskCompleted": true,
  "processIds": ["1234567890123456107"]
}
```

## Notes

- **Profile updates:** This operation uses the user create/update endpoint. Updating profile fields for a deactivated learner reactivates the learner. See [Update a user](/docs/users-and-groups/users/update-a-user/#notes).

- **Defaults:** Users are invited on the current date.
- **Username:** Required when UID is enabled for your Mindtickle instance, where it is the primary identifier for the user. Omitting it returns an HTTP 400 error. It is optional when UID is disabled, where it is not used as an identifier and the user's `email` is the primary identifier instead.
- **Email:** Required when UID is disabled for your Mindtickle instance, the default for most instances, where it is the primary identifier for the user. Omitting it returns an HTTP 400 error. It is optional when UID is enabled, where `username` is the primary identifier instead. Provide an email so the user receives platform invitations and reminders.
- **Clearing an email:** On UID-enabled instances, passing `"None"` as the email value removes the user's primary email. On UID-disabled instances, passing `"None"` returns a validation error. This value is case-insensitive.
- **Managers:** `username` is required for each manager entry when UID is enabled, and a blank or missing value returns an HTTP 400 error. `email` is required for each manager entry when UID is disabled, must be a valid email format, and an invalid value returns an HTTP 400 error.
- **Clearing a manager:** To clear a manager assignment, set the identifier value to `NONE` (uppercase).
- **Series entities:** If `entities` is omitted, the user is invited at the series level, and the behavior depends on the series configuration.

## Related

- [Invite users to a series](/docs/training/series/invite-users-to-a-series/): Invite several users to one series in a single call.
- [Invite users to a module](/docs/training/modules/invite-users-to-a-module/): Invite several users to one module in a single call.
- [Remove users from a series or module](/docs/training/series/remove-users-from-a-series-or-module/): Revoke access to a series or module.
- [Time zone values](/docs/users-and-groups/users/time-zone-values/): Time zone ID values for the timezone field.