# List & get contacts (v1)

> GET /api/v1/chatbots/:chatbotId/contacts to list (paged) and GET /api/v1/chatbots/:chatbotId/contacts/:contactId to fetch one by external id.

## GET /api/v1/chatbots/:chatbotId/contacts

List contacts for an agent. Page-based pagination, returned in a `pages` object alongside the total. `contactId` in the single-get path is the contact's `external_id`.

| Param | In | Type | Notes |
| --- | --- | --- | --- |
| chatbotId | path | integer | The agent id. |
| page | query | integer | Page number (default 1). |
| per_page | query | integer | Items per page. Clamped to 10–1000, default 100. |

```bash
curl "https://app.bookbag.ai/api/v1/chatbots/123/contacts?page=1&per_page=50" \
  -H "Authorization: Bearer $BOOKBAG_API_KEY"
```

## GET /api/v1/chatbots/:chatbotId/contacts/:contactId

Fetch a single contact by its `external_id`.

| Param | In | Type | Notes |
| --- | --- | --- | --- |
| chatbotId | path | integer | The agent id. |
| contactId | path | string | The contact's `external_id`. |

```bash
curl https://app.bookbag.ai/api/v1/chatbots/123/contacts/user_8821 \
  -H "Authorization: Bearer $BOOKBAG_API_KEY"
```

## Status codes

| Status | Meaning |
| --- | --- |
| 200 | Success. |
| 401 | Missing or invalid key. |
| 404 | Unknown chatbot/contact, or out of scope. Body: `{ message: "Resource not found" }`. |

See [Errors](/docs/api/errors).