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

## 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 must exist.

## Endpoint

```http
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](/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 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

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

Or:

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

Or:

```json
{
  "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:

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

```json
{
  "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](/docs/training/modules/invite-users-to-a-module/#backdated-module-invitations) separately.
- Use Unix timestamps in seconds for `invitedOn`. Replace the example dates with the actual historical invitation dates; future timestamps are rejected.

## Related

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