List conversations

GET/api/v1/conversations

Since: 1.14.0
Auth: Bearer key
SDK: client.listConversations()
operationId: listConversations

The clinic's conversations with patients, newest activity first, each with its patient. Filter by status, location, channel of the newest message and updated_since; page with cursor. To keep a copy in your system in step, store the time you start a sync and pass it as updated_since next time. Needs the scope conversations:read; every page you read is written to the clinic's audit log with the ids it showed. The response holds patient data and is never cached (Cache-Control: no-store); call it from your server only.

Request

Send the clinic's key in Authorization: Bearer (see API keys).

Query parameters

statusstring
Only open or only closed conversations.
One of openclosed
locationstring
A location id from GET /locations. The primary location also takes the conversations whose location is not known.
channelstring
Only conversations whose newest message is on this channel.
One of emailsmswhatsappinstagramchat
updated_sincestring (date-time)
Only conversations changed at or after this time (ISO 8601): a new message, a read, open or closed, or a change of the lead.
cursorstring
nextCursor of the previous page; omit for the first page.
limitinteger
Conversations per page, 1 to 100 (default 50).

cURLTypeScriptPHP

curl "https://app.pozyskajpacjenta.pl/api/v1/conversations?status=open&location=loc_wieliczka&channel=sms&updated_since=2026-10-12T08%3A00%3A00Z" \
  -H "Authorization: Bearer $PP_API_KEY"

import { PozyskajPacjentaClient } from "@pozyskajpacjenta/sdk";

const client = new PozyskajPacjentaClient({
  apiKey: process.env.PP_API_KEY ?? "",
  baseUrl: "https://app.pozyskajpacjenta.pl",
});

const { conversations, nextCursor } = await client.listConversations({
  status: "open",
  updatedSince: "2026-10-12T08:00:00Z",
});

<?php
$response = wp_remote_get(
    'https://app.pozyskajpacjenta.pl/api/v1/conversations?status=open&location=loc_wieliczka&channel=sms&updated_since=2026-10-12T08%3A00%3A00Z',
    array(
        'headers' => array( 'Authorization' => 'Bearer ' . getenv( 'PP_API_KEY' ) ),
        'timeout' => 10,
    )
);
if ( is_wp_error( $response ) ) {
    error_log( $response->get_error_message() );
    return;
}
$status = wp_remote_retrieve_response_code( $response );
$data   = json_decode( wp_remote_retrieve_body( $response ), true );

Response

200A page of conversations.

conversationsConversation[]required
The conversations, newest activity first.
Fields of each item (9)
- idstringrequired
  Conversation id.
- statusstringrequired
  open or closed. The clinic closes a conversation in its inbox; a new message from the patient opens it again.
  One of openclosed
- leadConversationLeadrequired
  The patient.
  Fields (9)
  - idstringrequired
    The lead id: the leadId POST /leads returns and webhook events carry.
  - namestring | nullrequired
    The patient's name; null when unknown.
  - phonestring | nullrequired
    The patient's phone; null when unknown.
  - emailstring | nullrequired
    The patient's e-mail; null when unknown.
  - messagestring | nullrequired
    The enquiry the patient sent: a form's message or the first chat message. null when there was none.
  - sourcestringrequired
    Where the lead came from: form, embed, api, manual, inbound or chat.
  - stagestringrequired
    The lead's stage in the clinic's CRM, e.g. new, scheduled, visited, not_interested.
  - locationIdstring | nullrequired
    The clinic location the enquiry is for (GET /locations); null when not known.
  - createdAtstring (date-time)required
    When the lead was created.
- lastChannelstring | nullrequired
  Channel of the newest message: email, sms, whatsapp, instagram or chat (the chat on the clinic's site). null before the first message.
  One of emailsmswhatsappinstagramchat
- lastMessageAtstring (date-time) | nullrequired
  Time of the newest message; null before the first one.
- lastInboundAtstring (date-time) | nullrequired
  Time of the patient's newest message; null when the patient has not written.
- unreadCountintegerrequired
  The patient's messages nobody at the clinic has opened yet.
- createdAtstring (date-time)required
  When the conversation began.
- updatedAtstring (date-time)required
  The later of the conversation's last change (a message, a read, open or closed) and the lead's (stage, contact data). The updated_since filter compares with it; delivery receipts do not change it.
nextCursorstring | nullrequired
Pass it as cursor for the next page; null on the last page.

200

Open conversations, one per page

{
  "conversations": [
    {
      "id": "Hm6pD1fGz4KqW8nLs2BvT",
      "status": "open",
      "lead": {
        "id": "Kq8vN2xWc0bLd4Te7YhJm",
        "name": "Piotr",
        "phone": "+48 601 200 300",
        "email": null,
        "message": null,
        "source": "inbound",
        "stage": "new",
        "locationId": null,
        "createdAt": "2026-10-12T09:15:20.000Z"
      },
      "lastChannel": "whatsapp",
      "lastMessageAt": "2026-10-12T09:15:20.000Z",
      "lastInboundAt": "2026-10-12T09:15:20.000Z",
      "unreadCount": 1,
      "createdAt": "2026-10-12T09:15:20.000Z",
      "updatedAt": "2026-10-12T09:15:20.000Z"
    }
  ],
  "nextCursor": "1791796520.Hm6pD1fGz4KqW8nLs2BvT"
}

Errors

Status	code	When
400	`invalid_query`	An unknown channel
401		No Authorization header
401		Unknown or rotated key
403	`missing_scope`	The key lacks conversations:read
403	`feature_disabled`	Conversations are not switched on for the clinic
429		Over 120 requests in this minute

Branch on the status and code, never on the Polish error text. All statuses in Errors.

400 · An unknown channel

{
  "error": "channel: jeden z email, sms, whatsapp, instagram, chat",
  "code": "invalid_query"
}

401 · No Authorization header

{
  "error": "missing Authorization: Bearer <klucz z panelu Ustawienia>"
}

401 · Unknown or rotated key

{
  "error": "invalid key"
}

403 · The key lacks conversations:read

{
  "error": "Klucz nie ma uprawnienia conversations:read. Placówka nadaje je w panelu: Ustawienia › Integracje › Klucz API.",
  "code": "missing_scope",
  "scope": "conversations:read"
}

403 · Conversations are not switched on for the clinic

{
  "error": "Rozmowy w API nie są włączone dla tej placówki.",
  "code": "feature_disabled"
}

429 · Over 120 requests in this minute

{
  "error": "przekroczono limit 120 zapytań/min"
}

Rate limit

120 requests per minute per key, shared by every endpoint.
Every response to a valid key carries RateLimit-Remaining and RateLimit-Reset; see Rate limits.

SDK method

client.listConversations(params?: { status?, locationId?, channel?, updatedSince?, cursor?, limit? }): Promise<ConversationList>

Throws ApiError 403 with code: "missing_scope" when the key lacks conversations:read.

The TypeScript tab above uses it. Install and errors: TypeScript SDK.