Invite a user to series and modules

Invites a user to one or more Mindtickle series or to specific modules within a series.

Prerequisites

Authentication and setup: A valid access token.
List all series: The series you invite the user to must exist.

Endpoint

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

Base URL: the standard REST host for your region. See 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 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.
`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:

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

{
  "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

{
  "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.
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.