> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact Conversation History

> Find email, SMS, and call conversations for one or more of your contacts, by their stored email addresses and phone numbers.

Retrieve conversation history using the contact's stored email addresses and phone
numbers. These endpoints include open and closed conversations by default and do
not require a customer classification or helpdesk ticket.

## One contact

```http theme={null}
GET /api/contacts/{contactId}/conversations?status=all&skip=0&limit=20
x-token: YOUR_API_KEY
```

## Several contacts

```http theme={null}
POST /api/contacts/conversations
x-token: YOUR_API_KEY
Content-Type: application/json

{"personIds":["CONTACT_ID_1","CONTACT_ID_2"],"status":"all","skip":0,"limit":20}
```

The POST is a read operation. Supply 1–20 contact IDs from your company; overlapping
conversations appear once. Every supplied contact must be active and belong to your
company or the request returns 404.

Both routes also accept `Authorization: DelegateToken YOUR_TOKEN` with `contacts:*`
read scope. API keys have company scope. Delegate-token requests follow the current
user's inbox/team/monitor access and contact-type sharing permissions. Inbox opt-outs
from automatic contact sharing are respected.

## Filters and pagination

| Parameter | Meaning |
| - | - |
| `status` | `all` (default), `open` (includes waiting/replied), or `closed` |
| `inboxId` | Optional channel ID that narrows accessible inboxes |
| `search` | Subject contains text, with comma-separated alternatives; up to 200 characters |
| `skip` | Number of conversations to skip; default 0, maximum 100000 |
| `limit` | Page size; default 20, maximum 60 |

GET uses query parameters; POST uses JSON fields. Results are ordered by latest
message, newest first. There is no recent-date window. Junk/deleted conversations, obsolete archived stream records,
and synthetic bulk-campaign activity rows are excluded. Closed conversations remain included.
Missing, archived, deleted, or foreign-company contacts return `NOT_FOUND`, even in a mixed batch.

Responses have `personIds`, `conversations`, `hasMore`, `skip`, and `limit` fields.
Each conversation includes its `_id`, subject, a preview of up to 500 characters,
type, status, participants, channel, message count and message/activity timestamps
where present. These are previews, not full transcripts.

When `hasMore` is true, repeat with `skip` increased by `limit`. New messages can
change ordering between pages. Contacts with no stored email or phone return an
empty list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.