---
title: "Create a user"
description: "Creates a user on the Mindtickle platform, optionally with profile fields, a time zone, groups, series and module assignments, and managers."
contentType: "api-reference"
url: "https://developer.mindtickle.com/docs/users-and-groups/users/create-a-user/"
---

## Prerequisites

1. [Authentication and setup](/docs/getting-started/authentication-and-setup/): A valid access token.

## Endpoint

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

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`.

## 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](/docs/users-and-groups/users/time-zone-values/) 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](/docs/getting-started/authentication-and-setup/#standard-base-url) and `ACCESS_TOKEN` to your access token. On an instance with UID disabled, this request creates a user without optional profile fields or assignments:

```bash
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](/docs/users-and-groups/users/check-process-status/#send-the-request); 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`:

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

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

```json
{
  "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](/docs/users-and-groups/users/update-a-user/#notes) 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](/docs/users-and-groups/users/check-process-status/): Check the status of the returned process IDs.
- [Time zone values](/docs/users-and-groups/users/time-zone-values/): The ID values accepted by the timezone field.
- [Update a user](/docs/users-and-groups/users/update-a-user/): Change the user after creating it.
- [Add a user to groups](/docs/users-and-groups/users/add-a-user-to-groups/): Add the user to more groups later.