Invite users to a module

Invites one or more users to a Mindtickle module of a series, with optional module relevance and a backdated invite timestamp.

View as Markdown

Prerequisites

Authentication and setup: A valid access token.
List all modules in a series: Get the Mindtickle IDs of the series and the module.

Endpoint

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.

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.

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

Or:

[
  {
    "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 if historical module completions need to be migrated.
Use Unix timestamps in seconds for the invited_on field.