---
title: "Get conversations for contacts"
method: POST
path: "/api/contacts/conversations"
tags: ["Contacts"]
---

# Get conversations for contacts

`POST /api/contacts/conversations`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/contacts/conversations`
- Auth: one of:
  - API key in header `x-token`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/contacts/conversations/post.ts> (a function with typed inputs; its response is checked against the schema)

Find real email, SMS, and call conversations by the contacts’ stored email addresses and phone numbers, without a helpdesk ticket requirement. Includes open and closed threads by default, with no recent-date cutoff. Excludes junk/deleted streams and synthetic bulk-campaign activity. Newest message first, across accessible inboxes. API keys have company scope; delegate tokens need contacts:* read scope and follow current membership, inbox/team/monitor and contact-type sharing permissions (respecting channel opt-outs). Every contact must be active and in the authenticated company. Empty addresses return an empty page.

## Request body

- object
  - `personIds` string[], required
  - `status` 'all' | 'open' | 'closed'
  - `inboxId` string: Channel meta.id; narrows authorized inboxes, never expands access.
  - `search` string: Subject contains text; comma-separated literal alternatives.
  - `skip` integer
  - `limit` integer

## Response `200`

A page of matching conversations.

- ContactConversationsResponse
  - `personIds` string[], required
  - `conversations` object[], required
    - `_id` string, required: Conversation stream ID.
    - `subject` string, nullable, required
    - `description` string, required
    - `type` string
    - `status` integer: 0 closed, 1 open, 2 waiting, 3 replied.
    - `assigneeId` string, nullable
    - `participants` string[]
    - `channel` object
      - `id` string
      - `type` string
    - `messageCount` integer, required
    - `metrics` object
      - `lastMessageAt` string, date-time
      - `lastActivityAt` string, date-time, nullable
      - `lastMessageDirection` 'in' | 'out', nullable
  - `hasMore` boolean, required: When true, request the next page with skip + limit.
  - `skip` integer, required
  - `limit` integer, required

## Other responses

- `400`: Invalid contact IDs, filters or pagination.
- `401`: Invalid or missing credentials.
- `403`: Missing scope, inactive user membership, guest user, or inaccessible inbox.
- `404`: One or more contacts are missing, archived, deleted or outside the company.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)