---
title: "Search users"
description: "Searches for users on Mindtickle by username or email, series, group, or module, and returns up to 50 records per page."
contentType: "api-reference"
url: "https://developer.mindtickle.com/docs/users-and-groups/users/search-users/"
---

## Prerequisites

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

## Endpoint

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

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 |
| --- | --- | --- | --- |
| `usernames` | Array[string] | Optional | Usernames of the users when UID is enabled for your Mindtickle instance. |
| `emails` | Array[string] | Optional | Email addresses of the users when UID is not enabled. |
| `seriesIds` | Array[string] | Optional | IDs of one or more series. |
| `groupIds` | Array[string] | Optional | IDs of one or more groups. |
| `moduleIds` | Array[string] | Optional | IDs of one or more 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). |

### Request example

```json
{
  "usernames": [
    "alex.fry@example.com",
    "anna.cruz@example.com",
    "rosalia.flores@example.com"
  ],
  "seriesIds": ["1234567890123456101"],
  "groupIds": ["1234567890123456102"],
  "moduleIds": ["1234567890123456103"]
}
```

## 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 | Completion flag for this request. This endpoint returns its result directly. |
| `totalSize` | integer | User count reported by the API. Use `done` and `nextRecordsUrl` to control pagination. |
| `done` | boolean | Flag for request completion. |
| `nextRecordsUrl` | string | URL to fetch the next 50 records. |
| `users` | Array[User] | Information on the users. |
| `users[].name` | string | Name of the user. |
| `users[].username` | string | Username of the user when UID is enabled for your Mindtickle instance, and the email address when UID is not enabled. |
| `users[].timezone` | string | Time zone of the user. |
| `users[].id` | string | Mindtickle ID of the user. |
| `users[].email` | string or null | Applicable only if UID is enabled for your Mindtickle instance. |
| `users[].userState` | string | Current state of the user: Active, Added, or Deactivated. |
| `users[].profile` | AttributeMap | Mindtickle profile fields information. |
| `users[].groupIds` | Array[string] | IDs of the groups that the user belongs to. |
| `users[].seriesEntities` | Array[SeriesEntity] | Series that the user is invited to. |
| `users[].source` | string | The system mechanism used to provision the user. Possible values include `_default` (REST API), `okta` (Okta SCIM), and `AzureAD` (Azure AD SCIM). |
| `users[].managers` | Array[Manager] | Information on the managers assigned to the user. |

### Response example

The example contains two user objects with `totalSize: 151` and `done: false`. Do not infer the total count from the length of the `users` array. The continuation URL is fictional; use the URL returned by your request.

```json
{
  "requestId": null,
  "responseCode": 0,
  "responseType": "USER_SEARCH_RESPONSE",
  "taskCompleted": true,
  "totalSize": 151,
  "done": false,
  "nextRecordsUrl": "https://api.example.com/services/data/v4.0/mtobjects/Users/NextRecords/NEXT_RECORDS_TOKEN",
  "users": [
    {
      "name": "Alex Fry",
      "username": "alex.fry@example.com",
      "timezone": "America/Costa_Rica",
      "id": "123456789abcd104",
      "email": null,
      "userState": "ACTIVE",
      "profile": {
        "dg": "Manager",
        "rg": "India",
        "rgn": "APAC",
        "dp": "Product"
      },
      "groupIds": [],
      "seriesEntities": [],
      "source": "_default",
      "managers": [
        {
          "username": "james.smith@example.com",
          "email": null,
          "key": "a_0"
        },
        {
          "username": "takumi.ishida@example.com",
          "email": null,
          "key": "a_1"
        }
      ]
    },
    {
      "name": "Anna Cruz",
      "username": "anna.cruz@example.com",
      "timezone": "America/Costa_Rica",
      "id": "123456789abcd105",
      "email": null,
      "userState": "ACTIVE",
      "profile": {
        "dg": "Manager",
        "rg": "India",
        "rgn": "APAC",
        "dp": "Product"
      },
      "groupIds": [],
      "seriesEntities": [],
      "source": "_default",
      "managers": [
        {
          "username": "james.smith@example.com",
          "email": null,
          "key": "a_0"
        },
        {
          "username": "takumi.ishida@example.com",
          "email": null,
          "key": "a_1"
        }
      ]
    }
  ]
}
```

## Notes

- **Behavior:** An empty JSON object `{}` searches all users in the learning site. Results are still paginated.
- **Limits:** A maximum of 50 records are returned per request. Use `nextRecordsUrl` from the response to fetch subsequent sets of 50 records.
- **Pagination:** Send each subsequent request as `GET NEXT_RECORDS_URL` with the header `Authorization: Bearer ACCESS_TOKEN`. The original request is POST, but subsequent requests must use GET.
- **Validation:** When searching for multiple users, send each username or email as a separate string in the corresponding JSON array.
- **Read-only fields:** `source` is read-only. Values passed for it in the request payload are silently ignored.

## Related

- [Get a user](/docs/users-and-groups/users/get-a-user/): Read one user by Mindtickle user ID.
- [Update a user](/docs/users-and-groups/users/update-a-user/): Update a user found by this search.
- [Search groups](/docs/users-and-groups/groups/search-groups/): Find the group IDs to filter by.