---
title: "Invite users to a module"
description: "Invites one or more users to a Mindtickle module of a series, with optional module relevance and a backdated invite timestamp."
contentType: "api-reference"
url: "https://developer.mindtickle.com/docs/training/modules/invite-users-to-a-module/"
---

## Prerequisites

1. [Authentication and setup](/docs/getting-started/authentication-and-setup/): A valid access token.
2. [List all modules in a series](/docs/training/modules/list-all-modules-in-a-series/): Get the Mindtickle IDs of the series and the module.

## Endpoint

```http
POST /services/data/v4.0/mtobjects/Series/SERIES_ID/Module/MODULE_ID
```

Replace `SERIES_ID` and `MODULE_ID` with the Mindtickle IDs of the series and the module.

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

## Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `SERIES_ID` | string | Required | Mindtickle ID of the series to which the module belongs. |
| `MODULE_ID` | string | Required | Mindtickle ID of the module that you want to assign to one or more users. |

## Request

The body is an array of objects with the following fields.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `userid` | string | Conditional | Mindtickle ID of the user to invite. Required if `username` is omitted. |
| `username` | string | Conditional | Mindtickle username or email address of the user to invite. Required if `userid` is omitted. |
| `module_relevance` | string | Not specified | Define the relevance of the module for the user: `required`, `optional`, or `unmarked`. |
| `invited_on` | number | Optional | Unix timestamp in seconds for the module invitation. Use this for backdating; future timestamps are rejected. |

### Request example

The examples use historical Unix timestamps in seconds. Replace them with the actual invitation dates. Omit `invited_on` to invite users at the current time.

```json
[
  {
    "userid": "123456789abcd101",
    "module_relevance": "optional",
    "invited_on": 1747094400
  },
  {
    "userid": "123456789abcd102",
    "module_relevance": "required",
    "invited_on": 1747094400
  }
]
```

Or:

```json
[
  {
    "username": "alex.fry@example.com",
    "module_relevance": "optional",
    "invited_on": 1747094400
  },
  {
    "username": "anna.cruz@example.com",
    "module_relevance": "unmarked",
    "invited_on": 1747094400
  }
]
```

## Response

Returns `200 OK` with the message `Users invited to module successfully.`

## Errors

| Status | Error |
| --- | --- |
| `400` | Invalid request, including an empty array, more than 500 users, a missing user identifier, invalid module relevance, or a future `invited_on` timestamp. |
| `401` | Invalid token. |
| `404` | Invalid series ID, module ID, user ID, or username. |
| `429` | Too many calls. Retry after 5 min. |
| `500` | Internal server error. |

## Notes

- **Limits:** You can invite a maximum of 500 users per request.
- **Identifier choice:** You must provide either `userid` or `username` for each object in the array.
- **Usernames:** Provide the usernames of the users if UID is enabled for your Mindtickle instance. Provide their email address if UID is not enabled.
- **Defaults:** If `invited_on` is omitted, the current date and time is used.

## Backdated module invitations

You can invite users to a module with a backdated timestamp using the `invited_on` field. The platform then recognizes completion dates earlier than the current invite date, which keeps historical completions accurate and aligns completion dates for rewards and reporting.

- The backdated invite date must be earlier than the completion date.
- Completion APIs respect backdated module invitations and accept earlier completion timestamps.
- Module invitations must be backdated independently of [series invitations](/docs/training/series/invite-users-to-a-series/#backdated-series-invitations) if historical module completions need to be migrated.
- Use Unix timestamps in seconds for the `invited_on` field.

## Related

- [Invite users to a series](/docs/training/series/invite-users-to-a-series/): Invite users to the whole series, and backdate series invitations.
- [Remove users from a series or module](/docs/training/series/remove-users-from-a-series-or-module/): Remove users from the module.
- [Complete modules for multiple users](/docs/training/modules/complete-modules-for-multiple-users/): Mark the module complete once users are invited.