# List users

`GET /user.list`

## Description

List workspace members, or hydrate an explicit ordered set of principal IDs.

Without `ids`, this is the active workspace member directory: guests,
bots, and archived/deactivated members are never enumerated. Members are
returned in the order they were added to the account.

With `ids`, the endpoint becomes an unpaginated principal hydrator. Pass one
comma-separated value containing at most 100 bare or tagged IDs. Duplicate
tokens are deduplicated in first-seen order; resolved entries are returned
in that order. Unknown IDs, groups, and unauthorized principals are silently
omitted. Explicit lookup may resolve archived/deactivated users and
authorized automated actors. The response keeps the existing `users` key
but its entries are principals, and `nextCursor` is omitted.

`ids` cannot be combined with `q`, `limit`, or `cursor`. `expand=status`
remains supported in either mode.

See [Identity & Principals](/docs/guides/identity-and-principals).

**Required scope:** `user:read` (add `user:read.email` to include email addresses, `user:read.status` to expand presence status and `willReturn`)

**Access:** Organization and Personal.

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `ids` | query | string | No | One comma-separated list of up to 100 bare or tagged principal IDs. Repeating the `ids` query parameter, including empty tokens, or combining it with `q`, `limit`, or `cursor` returns `invalid_paramet |
| `q` | query | string | No | Case-insensitive member-directory filter by name. Also matches email when the token has `user:read.email`. Cannot be combined with `ids`.  |
| `limit` | query | integer | No | The number of directory members to return per response. Default is 10. Cannot be combined with `ids`. |
| `cursor` | query | string | No | Opaque directory cursor from a previous response's `nextCursor`. Cannot be combined with `ids`. |
| `expand` | query | string | No | Comma-separated list of additional fields. Supported: `status` (requires `user:read.status`). Expanding `status` also returns `willReturn` when set. |

## Responses

### 200 - Directory members or explicitly hydrated principals retrieved successfully.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `users` | User[] | No | Principal entries. In directory mode every entry is an active workspace member. |
| `nextCursor` | string | No | Pagination cursor for fetching the next page of results |

**User** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | The principal's unique address identifier. |
| `type` | "user" | "bot" | Yes | Stable public principal type. All automated actors are `bot`. |
| `name` | string | Yes | Display name of the principal. |
| `imageUrl` | string | No | URL of the principal's profile image. |
| `email` | string | No | Email address for a member or guest (requires `user:read.email`). Omitted for bots. |
| `isGuest` | "true" | No | Present and true only for users without membership in the caller's account. |
| `isAdmin` | boolean | No | Whether a workspace member is an admin. Present for members even when false; omitted for guests and bots. |
| `jobTitle` | string | No | Workspace member's job title. Omitted for guests and bots. |
| `location` | string | No | Workspace member's location. Omitted for guests and bots. |
| `status` | "checkedIn" | "checkedOut" | No | User's current presence status. Only included when `expand=status` is requested and the `user:read.status` scope is granted. |
| `willReturn` | object | No | Out-of-office / "Will Return" status. Present only when `expand=status` is requested, the `user:read.status` scope is granted, and the user has a future return time. A user can be `checkedIn` and stil |
| `available` | boolean | No | Whether the user is currently available for visitors. Only included when `expand=available` is requested and the `user:read.status` scope is granted. |
| `botCode` | string | No | Classic bot persona identifier, when available. |
| `integrationId` | string | No | Integration/client identifier for an automated actor, when available. |

**willReturn**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `returnTime` | string | Yes | When the user is expected to return (RFC 3339). |
| `reason` | string | No | Optional absence message (e.g. "On Vacation"). |
| `outOfRoam` | boolean | No | When true, multi-day Out of Roam that persists across check-ins. When false or omitted, same-day Will Return Today. |

### 400 - Bad request, including malformed/empty IDs, more than 100 raw tokens, repeated `ids` parameters, or `ids` combined with `q`, `limit`, or `cursor`.

### 401 - Presented invalid authentication credentials.

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/user-list*