Add or update multiple users

Adds or updates multiple users on Mindtickle in a single request, with profile fields, time zones, groups, series and module assignments, and managers.

View as Markdown

Prerequisites

Authentication and setup: A valid access token.

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	Username of the user when UID is enabled for your Mindtickle instance. When UID is disabled, use the `email` field instead.
`id`	string	Recommended	Mindtickle ID of the user.
`timezone`	string	Optional	Time zone ID value for the time zone you want to configure for 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 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]	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 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",
    "id": "123456789abcd101",
    "timezone": "America/Costa_Rica",
    "profile": {
      "dp": "abc",
      "lang": "Italian"
    },
    "groupIds": ["1234567890123456102"],
    "seriesEntities": [
      {
        "seriesId": "1234567890123456103",
        "entities": ["1234567890123456104"]
      }
    ],
    "managers": [
      {
        "username": "james.smith@example.com",
        "key": "a_0"
      }
    ]
  },
  {
    "name": "Anna Cruz",
    "username": "anna.cruz@example.com",
    "id": "123456789abcd105",
    "timezone": "America/Costa_Rica",
    "profile": {
      "dp": "abc"
    },
    "groupIds": ["1234567890123456102"],
    "seriesEntities": [
      {
        "seriesId": "1234567890123456103",
        "entities": ["1234567890123456104"]
      }
    ],
    "managers": [
      {
        "username": "james.smith@example.com",
        "key": "a_0"
      },
      {
        "username": "takumi.ishida@example.com",
        "key": "a_1"
      }
    ]
  }
]

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": ["1234567890123456106"]
}

Notes

Async processing: The request is queued, and the response returns process IDs you use to check the result.
Email updates: On UID-enabled instances, use "None" to remove the primary email. Do not use this endpoint to replace an existing email address with a different address.
Limits: Mindtickle recommends adding or updating a maximum of 500 users at once.
Reactivation: Updating profile fields for a deactivated learner reactivates the learner.
Validation: List each user separately in the array, as shown in the request example.
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.