Add multiple users to groups

Adds multiple users to one or more Mindtickle groups in a single request.

Prerequisites

Authentication and setup: A valid access token.
Create a group: The groups in groupIds must exist.

Endpoint

PUT /services/data/v4.0/mtobjects/Users

Base URL: the standard REST host for your region. See Base URLs.

Headers: Authorization: Bearer ACCESS_TOKEN, Content-Type: application/json.

Request

The body is an array of user objects, one object per user.

Parameter	Type	Required	Description
`name`	string	Optional	Name of the user.
`username`	string	Required if UID enabled	Unique identifier for the users you want to add to one or more groups. Provide the username when UID is enabled. When UID is disabled, use the `email` field instead.
`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.
`email`	string	Required if UID disabled	Email address of the user, used for communication such as invitation and reminder emails, whatever your instance’s UID mode. Primary identifier when UID is disabled, the default for most instances.
`groupIds`	Array[string]	Required	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 within each entry	ID of the series. Required when an entry is included in `seriesEntities`.
`seriesEntities[].entities`	Array[string]	Optional	IDs of the modules.
`source`	string	Read-only	The system mechanism used to provision the user. Possible values include `_default` (REST API), `okta` (Okta SCIM), and `AzureAD` (Azure AD SCIM).
`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. Must be a valid email format.
`managers[].key`	string	Optional	Mindtickle relationship shortkey for the Manager attribute.

Request example

This example uses usernames for a UID-enabled instance. When UID is disabled, use email to identify each user and manager, as shown in Create a user.

[
  {
    "name": "Alex Fry",
    "username": "alex.fry@example.com",
    "timezone": "America/Costa_Rica",
    "id": "123456789abcd101",
    "profile": {
      "dp": "abc"
    },
    "groupIds": ["1234567890123456102", "1234567890123456103"],
    "seriesEntities": [
      {
        "seriesId": "1234567890123456104",
        "entities": ["1234567890123456105"]
      }
    ],
    "managers": [
      {
        "username": "james.smith@example.com",
        "key": "a_0"
      }
    ]
  },
  {
    "name": "Anna Cruz",
    "username": "anna.cruz@example.com",
    "id": "123456789abcd106",
    "timezone": "America/Costa_Rica",
    "profile": {
      "dp": "abc"
    },
    "groupIds": ["1234567890123456102", "1234567890123456103"],
    "seriesEntities": [
      {
        "seriesId": "1234567890123456104",
        "entities": ["1234567890123456105"]
      }
    ],
    "managers": [
      {
        "username": "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.
Async processing: The request is queued, and the response returns process IDs you use to check the result.
Limits: Mindtickle recommends adding users to a maximum of 50 groups at once.
Validation: Send each group ID as a separate string in the groupIds JSON array.
Email value: 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: A blank or missing username in a manager entry when UID is enabled returns an HTTP 400 error. An invalid email in a manager entry when UID is disabled returns an HTTP 400 error. To clear a manager assignment, set the identifier value to NONE in uppercase. See the Notes on Update a user for an example.
Read-only fields: source is read-only. Values passed for it in the request payload are silently ignored.