---
title: "List contacts"
method: GET
path: "/v1/users/{user_id}/entities"
tags: ["Entities"]
---

# List contacts

`GET /v1/users/{user_id}/entities`

## Request

- Base URL: `http://0.0.0.0:3000`
- URL: `http://0.0.0.0:3000/v1/users/{user_id}/entities`
- Auth: none declared

Returns contacts (people and bots) that the authenticated user has communicated with.

**Use cases**:
- Discover entity IDs for filtering messages by sender via `GET /v1/users/:user_id/messages?entity_id=ent_xxx`
- Build a contact picker UI
- Show sender details in inbox views

**Filtering**:
- `search`: Case-insensitive substring match on contact name, or exact match on an external ID (email address, Slack user ID)
- `entity_type`: Filter by type (e.g., "person", "bot")
- `is_bot`: Filter by bot status (true/false)

**Pagination (cursor-only)**:
- `limit`: Maximum number of contacts per page (default: 50, max: 100)
- `cursor`: Opaque token from `pagination.next_cursor` of a prior response. Pass it back unchanged to fetch the next page. Omit on the first page.

The response `pagination` object contains `limit`, `has_more`, and (when `has_more=true`) `next_cursor`. There is no `offset` and no `total_count` — partners walk pages forward via cursor and use `has_more` to detect the last page.

**Examples**:
```
# List all contacts
GET /v1/users/:user_id/entities

# Search by name or email
GET /v1/users/:user_id/entities?search=john

# Only non-bot contacts
GET /v1/users/:user_id/entities?is_bot=false

# Filter by type
GET /v1/users/:user_id/entities?entity_type=person
```

## Path parameters

- `user_id` string, uuid, required

## Query parameters

- `search` string
- `entity_type` string
- `is_bot` 'true' | 'false'
- `limit` string
- `cursor` string

## Response `200`

Default Response

- object
  - `success` true, required
  - `data` object[], required
    - `id` string, required
    - `name` string, required
    - `entity_type` string, required
    - `external_ids` string[], required
    - `is_bot` boolean, required
    - `avatar_uri` string, nullable, required
  - `pagination` union, required
    - object
      - `limit` number, required
      - `has_more` true, required
      - `next_cursor` string, required
    - object
      - `limit` number, required
      - `has_more` false, required

## Other responses

- `400`: Default Response
- `403`: Default Response
- `500`: Default Response

---

[API](https://skmtc.dev/attrove/apis/attrove-api.md) · [All operations](https://skmtc.dev/attrove/apis/attrove-api/llms.txt) · [OpenAPI document](https://skmtc.dev/attrove/apis/attrove-api/revisions/fcdc818b45cb?raw)