> For the complete documentation index, see [llms.txt](https://docs.clearfeed.ai/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clearfeed.ai/api/reference/api-reference/users.md).

# Users

Look up users of your connected Slack workspace by user ID or email address.

## User Object

Users are represented as JSON objects with the following properties:

<table data-full-width="true"><thead><tr><th width="150">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>The Slack user ID.</td></tr><tr><td>name</td><td>string</td><td>The display name of the user.</td></tr><tr><td>deleted</td><td>boolean</td><td>Whether the user has been deactivated in Slack.</td></tr><tr><td>is_bot</td><td>boolean</td><td>Whether the user is a bot.</td></tr><tr><td>email</td><td>string</td><td>The email address of the user. Only included when users are looked up by <code>emails</code>.</td></tr></tbody></table>

## Look Up Users

<mark style="color:blue;">`GET`</mark> `https://api.clearfeed.app/v1/rest/users`

Returns the users matching the given user IDs or email addresses.

#### Query Parameters

Exactly one of `ids` or `emails` is required.

| Name     | Type         | Description                                                                                                        |
| -------- | ------------ | ------------------------------------------------------------------------------------------------------------------ |
| `ids`    | string array | Slack user IDs to look up. Up to 100 unique values, comma-separated (`?ids=U1,U2`) or repeated (`?ids=U1&ids=U2`). |
| `emails` | string array | Email addresses to look up. Up to 100 unique values, in the same formats as `ids`. Matching is case-insensitive.   |

{% tabs %}
{% tab title="200 OK (By IDs)" %}
`GET /v1/rest/users?ids=U05HQ3DLCGJ,U05J32X71UH`

```json
{
  "users": [
    {
      "id": "U05HQ3DLCGJ",
      "name": "Jane Doe",
      "deleted": false,
      "is_bot": false
    },
    {
      "id": "U05J32X71UH",
      "name": "John Smith",
      "deleted": true,
      "is_bot": false
    }
  ],
  "response_metadata": {
    "next_cursor": null,
    "count": 2
  }
}
```

{% endtab %}

{% tab title="200 OK (By Emails)" %}
`GET /v1/rest/users?emails=jane@acme.com`

```json
{
  "users": [
    {
      "id": "U05HQ3DLCGJ",
      "name": "Jane Doe",
      "deleted": false,
      "is_bot": false,
      "email": "jane@acme.com"
    }
  ],
  "response_metadata": {
    "next_cursor": null,
    "count": 1
  }
}
```

{% endtab %}

{% tab title="400: Bad Request" %}
Returned when both `ids` and `emails` are provided, or neither is.

```json
{
  "message": ["Exactly one of ids, emails must be present."],
  "error": "BAD_REQUEST"
}
```

{% endtab %}

{% tab title="403: Forbidden" %}

```json
{
  "message": "Forbidden resource",
  "error": "FORBIDDEN"
}
```

{% endtab %}
{% endtabs %}

### Notes

* Users are returned in the order requested. IDs or emails that don't match a user are omitted, so `count` may be lower than the number requested.
* This operation is recorded in [audit logs](/api/reference/api-reference/audit-logs.md) as `Listed users` under the `Account` resource type.