# List users

`GET /user.list`

## Description

List all users in the account.

Users are returned in the order they were added to the account.

**Access:** Organization only.

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

---

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

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `limit` | query | integer | No | The number of users to return per response. Default is 10. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |
| `expand` | query | string | No | Comma-separated list of additional fields to include in the response. Supported values: `status` (requires `user:read.status` scope). |

## Responses

### 200 - Info retrieved successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `users` | User[] | No |  |
| `nextCursor` | string | No | Pagination cursor for fetching the next page of results |

**User** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | TaggedUUID | Yes | The User ID |
| `name` | string | Yes | Display name of the user |
| `imageUrl` | string | No | URL of the user's profile image |
| `email` | string | No | Email address of the user (requires `user:read.email` scope) |
| `isAdmin` | boolean | No | Whether the user is an admin of the Roam |
| `jobTitle` | string | No | User's job title |
| `location` | string | No | User's location |
| `status` | "checkedIn" | "checkedOut" | No | User's current presence status. Only included when `expand=status` is requested and the `user:read.status` scope is granted. |

**TaggedUUID**:

A UUID prefixed by a tag identifying the specific type of object

#### Example Response

```json
{
  "users": [
    {
      "id": "U-709b8a57-70bc-427a-b6f0-b16ba5297f8c",
      "name": "Alex Chen",
      "imageUrl": "https://ro.am/card-images/7be550c0-6994-4b8f-9a41-48825c6fc62a",
      "email": "alex.chen@example.com",
      "isAdmin": false,
      "status": "checkedIn"
    },
    {
      "id": "U-af6663d5-0f37-4105-95df-4fea20ef7c7c",
      "name": "Jordan Smith",
      "imageUrl": "https://ro.am/card-images/41b2a910-e37f-4ffb-9cdd-5be7d05e9f6f",
      "email": "jordan.smith@example.com",
      "isAdmin": true,
      "status": "checkedOut"
    },
    {
      "id": "U-f589a8cb-78ac-493e-8719-0fa8a22f65e0",
      "name": "Taylor Williams",
      "imageUrl": "https://ro.am/photos/people/taylor-williams.png",
      "email": "taylor@example.com",
      "isAdmin": false,
      "status": "checkedIn"
    }
  ],
  "nextCursor": "546"
}
```

### 400 - Bad request.

### 401 - Presented invalid authentication credentials.

### 405 - An unsupported method was requested.

### 500 - An internal error occured.

---

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