Invite users to a series

Invites one or more users to a Mindtickle series, with an optional backdated invite timestamp.

Prerequisites

Authentication and setup: A valid access token.
List all series: The series must exist.

Endpoint

POST /services/data/v4.0/mtobjects/Series/SERIES_ID/Users

Replace SERIES_ID with the Mindtickle ID of the series.

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 that you want to assign to one or more users.

Request

Parameter	Type	Required	Description
`userids`	Array[string]	Conditional	Mindtickle IDs of the users that you want to invite to the series. Send each ID as a separate string in the JSON array.
`usernames`	Array[string]	Conditional	Mindtickle usernames or email addresses of the users that you want to invite to the series.
`userInvitations`	Array[Object]	Conditional	Use this object to invite users with a specific timestamp.
`userInvitations[].userId`	string	Required	The Mindtickle ID of the user.
`userInvitations[].invitedOn`	number	Optional	Unix timestamp in seconds for the series invitation. Must be at least `1000000` and must not be in the future.

Provide a nonempty array in one of userids, usernames, or userInvitations. A nonempty userInvitations array takes precedence.

Request example

{
  "userids": ["123456789abcd101", "123456789abcd102", "123456789abcd103"]
}

Or:

{
  "usernames": ["alex.fry@example.com", "anna.cruz@example.com", "james.smith@example.com"]
}

Or:

{
  "userInvitations": [
    {
      "userId": "123456789abcd101",
      "invitedOn": 1747094400
    },
    {
      "userId": "123456789abcd102",
      "invitedOn": 1747094400
    },
    {
      "userId": "123456789abcd103",
      "invitedOn": 1747094400
    }
  ]
}

Response

Returns 200 OK with the message Users invited to series successfully.

Errors

Status	Error
`400`	Invalid request, including more than 40 users, a future `invitedOn` timestamp, or an `invitedOn` value below `1000000`.
`401`	Invalid token.
`404`	Invalid seriesid/userid/username.
`429`	Too many calls. Retry after 5 min.
`500`	Internal server error.

Notes

Limits: You can invite a maximum of 40 users per request.
Identifier choice: You must provide one of userids, usernames, or userInvitations. userInvitations takes preference over the other two fields.
Usernames: Provide the usernames of the users if UID is enabled for your Mindtickle instance. Provide their email addresses if UID is not enabled.
Defaults: If invitedOn is omitted, the current date and time is used by default.

Backdated series invitations

You can invite users to a series with a backdated timestamp using the invitedOn 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.

To backdate a series invitation, use this endpoint:

POST /services/data/v4.0/mtobjects/Series/SERIES_ID/Users

{
  "userInvitations": [
    {
      "userId": "123456789abcd101",
      "invitedOn": 1747094400
    },
    {
      "userId": "123456789abcd102",
      "invitedOn": 1747094400
    }
  ]
}

Backdate the invitation before recording a historical completion. The resulting invitation date must precede the completion date.
Series-level backdated invitations only affect the series. If modules within the series also require historical completions to be migrated, you must backdate module invitations separately.
Use Unix timestamps in seconds for invitedOn. Replace the example dates with the actual historical invitation dates; future timestamps are rejected.