Create a user

Prerequisites

1. Authentication and setup: A valid access token.

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. Primary identifier when UID is enabled for your Mindtickle instance. Not used as an identifier when UID is disabled.
id	string	Optional	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.

Minimal request

Set BASE_URL to the standard REST host for your region and ACCESS_TOKEN to your access token. On an instance with UID disabled, this request creates a user without optional profile fields or assignments:

curl --request POST \
  --url "${BASE_URL:?Set BASE_URL}/services/data/v4.0/mtobjects/User" \
  --header "Authorization: Bearer ${ACCESS_TOKEN:?Set ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Alex Fry","email":"alex.fry@example.com"}'

If UID is enabled, include "username":"alex.fry@example.com" in the body. You can keep email so the user receives invitations and reminders. The request returns HTTP 200 when it is queued. Check each returned process ID using Check process status; acceptance does not mean user creation has finished.

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

Notes

• Async processing: The request is queued, and the response returns process IDs you use to check the result.
• Validation: Omitting username when UID is enabled returns an HTTP 400 error. Omitting email when UID is disabled returns an HTTP 400 error.
• 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.
• Clear a manager: Set the manager 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.

Related

• Check process status: Check the status of the returned process IDs.
• Time zone values: The ID values accepted by the timezone field.
• Update a user: Change the user after creating it.
• Add a user to groups: Add the user to more groups later.