> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Users search

The users search API lets you find, filter and analyze users within your organization using flexible Typesense-powered queries. You can search by name, email, or user UID.

## Example use cases

* **Get all users in the organization**

  ```json theme={null}
  {
    "query_by": "*",
    "q": "*"
  }
  ```

* **Find users by email**

  ```json theme={null}
  {
    "query_by": "*",
    "filter_by": "userEmail:=john.doe@company.com",
    "q": "*"
  }
  ```

***

## Searchable fields

Only the following fields can be used for searching:

| Field | Type   | Description          |
| ----- | ------ | -------------------- |
| name  | string | User's full name     |
| email | string | User's email address |
| uid   | string | Unique user UID      |

## User search response fields

Below are all the fields you may see in a user search result. Teams and sidebar preferences are included by default.

### Core fields

| Field               | Type    | Description                             |
| ------------------- | ------- | --------------------------------------- |
| id                  | string  | Unique user identifier                  |
| uid                 | string  | Unique user UID                         |
| authId              | string  | Authentication ID                       |
| organizationId      | string  | Organization ID                         |
| name                | string  | User's full name                        |
| email               | string  | User's email address                    |
| userType            | string  | User type (ORG\_ADMIN, BOT\_USER, etc.) |
| isActive            | boolean | Whether the user is active              |
| status              | string  | User status (ACTIVE, INACTIVE, etc.)    |
| primaryTeamId       | string  | Primary team ID (can be null)           |
| lastLoginAt         | string  | Last login timestamp (ISO8601)          |
| metadata            | object  | Custom metadata                         |
| avatarUrl           | string  | User avatar URL                         |
| timezone            | string  | User's timezone                         |
| externalSinks       | array   | External integrations                   |
| createdAt           | string  | Creation timestamp (ISO8601)            |
| updatedAt           | string  | Last update timestamp (ISO8601)         |
| deletedAt           | string  | Deletion timestamp (ISO8601)            |
| businessHoursConfig | object  | Business hours configuration            |

### Default extended fields

These fields are included in every response:

| Field              | Type   | Description                        |
| ------------------ | ------ | ---------------------------------- |
| teams              | array  | Array of teams the user belongs to |
| sidebarPreferences | object | User's sidebar preferences         |

### Team structure

When `teams` is included, each team object contains:

| Field         | Type    | Description                      |
| ------------- | ------- | -------------------------------- |
| id            | string  | Team identifier                  |
| name          | string  | Team name                        |
| icon          | string  | Team icon                        |
| color         | string  | Team color                       |
| identifier    | string  | Team identifier                  |
| description   | string  | Team description                 |
| teamOwner     | string  | Team owner name                  |
| teamOwnerId   | string  | Team owner ID                    |
| isActive      | boolean | Whether team is active           |
| isPrivate     | boolean | Whether team is private          |
| createdAt     | string  | Team creation timestamp          |
| updatedAt     | string  | Team update timestamp            |
| isDefaultTeam | boolean | Whether this is the default team |

### Sidebar preferences structure

When `sidebarPreferences` is included, it contains:

| Field       | Type   | Description              |
| ----------- | ------ | ------------------------ |
| openTeams   | object | Open teams configuration |
| pinnedTeams | array  | Array of pinned team IDs |
| teamOrder   | array  | Team display order       |
| lastTeam    | string | Last accessed team ID    |

> For a full list, see the UserSearchResponseDto in the API reference.

***

## Filtering options

You can filter users using the `filter_by` parameter with Typesense syntax. The following filters are available:

### Available filters

* **By user ID**: `userId:=URR9A99BDJ`
* **By email**: `userEmail:=user@example.com`
* **By name**: `userName:=shakthi`

### Combined filters

You can combine multiple filters using `&&`:

```json theme={null}
{
  "query_by": "name",
  "filter_by": "userId:=USER123ABC&&userEmail:=john.doe@company.com&&userName:=john",
  "q": "*"
}
```

### Filter examples

* **Find user by email only**
  ```json theme={null}
  {
    "filter_by": "userEmail:=john.doe@company.com"
  }
  ```

* **Find user by name only**
  ```json theme={null}
  {
    "filter_by": "userName:=john"
  }
  ```

* **Find user by UID only**
  ```json theme={null}
  {
    "filter_by": "userId:=USER123ABC"
  }
  ```