Encounters — iClinic API docs

List encounters

GET/api/integration/v1/encounters

Returns the encounters whose visitDate falls in the range [from, to], newest first. Requires the encounters:read scope.

Cancelled encounters are excluded by default. To mark an appointment as “Cancelled”, call the endpoint with status=all (every status) or status=CANCELLED.

Query parameters

Parameter	Description
`from`string · daterequired	First visit date, `YYYY-MM-DD`, in the clinic's local time.
`to`string · dateoptional	Last visit date, inclusive. Default: today. The range `from`–`to` can span at most 31 days.
`status`string · enumoptional	If omitted: every status except `CANCELLED`. `all`: every status, including cancelled. Or one of `NEW` `ONGOING` `FINISHED` `REOPENED` `LOCKED` `CANCELLED`. Case-insensitive.
`page`integeroptional	Page number, starting at `0`. Default `0`.
`pageSize`integeroptional	From 1 to 500. Default `200`.

Response 200

Hover over a row, or move to it with Tab, to see where that field sits in the JSON.

Field	Meaning
`requestId`string	The ID of the request. It matches the `X-Request-Id` header. Include it when you contact support.
`total`integer	Total number of encounters that match the filter, across all pages.
`encounters`array	The encounters on the current page. The response also returns `from`, `to`, `page` and `pageSize` exactly as you sent them (after defaults are applied).

An encounter

Field	Meaning
`encounterUuid`string	Deduplication key. A stable ID of the encounter. It never changes.
`id`string	The record code shown to users. For reference only. It can be issued again, so do not use it as a deduplication key.
`patientName`string	Patient name.
`phone`string \| null	Phone number; `null` if the clinic has no number.
`visitDate`date	Visit date, `YYYY-MM-DD`, in the clinic's local time. The system stores the date, not the time of the visit.
`checkedInAt`date-time \| null	Check-in time, in Coordinated Universal Time (UTC), when it is known; otherwise `null`. Do not read `null` as “has not arrived”; rely on `status` instead.
`completedAt`date-time \| null	Time the examination ended (UTC), or `null`.
`status`enum	`NEW` arrived / checked in `ONGOING` examination in progress `FINISHED` examination finished `REOPENED` reopened `LOCKED` record locked `CANCELLED` cancelled
`patientType`enum	`NEW` new patient `OLD` returning patient `RE_EXAMINATION` scheduled follow-up
`diagnosis`string	Diagnosis; an empty string if there is none yet.
`icd10Code`string	ICD-10 diagnosis code; an empty string if there is none yet.
`patientId`string \| null	Added in 1.1.0. The patient's `id` in `/patients`; `null` if the encounter is not linked to a patient record.
`followUpDate`date \| null	Added in 1.1.0. The follow-up date the doctor scheduled, `YYYY-MM-DD`; `null` if no follow-up is scheduled.
`updatedAt`date-time	Added in 1.1.0. When the encounter last changed (UTC).

Errors

Error code	When
`INVALID_DATE`400	`from` or `to` is missing or malformed.
`INVALID_RANGE`400	`to` is before `from`, or the range is longer than 31 days.
`INVALID_STATUS`400	`status` is not valid.
`INVALID_PAGE`400	`page` or `pageSize` is not valid.
`INSUFFICIENT_SCOPE`403	The API key does not have the `encounters:read` scope.

Every endpoint can also return 401, 429 and 5xx. See Error codes.

curl -sS "https://iclinic.phongkhamhieploi.vn/api/integration/v1/encounters?from=2026-09-14&to=2026-09-19&status=all&page=0&pageSize=200" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

const BASE = 'https://iclinic.phongkhamhieploi.vn/api/integration/v1';

// Node 18+ (fetch is built in). Walks through every page.
export async function listEncounters({ from, to, status = 'all' }) {
  const pageSize = 200;
  const encounters = [];
  for (let page = 0; ; page += 1) {
    const url = new URL(`${BASE}/encounters`);
    url.search = new URLSearchParams({ from, to, status, page, pageSize });
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.ICLINIC_API_KEY}` },
    });
    if (!res.ok) {
      const { error } = await res.json();
      throw new Error(`${res.status} ${error.code}: ${error.message}`);
    }
    const body = await res.json();
    encounters.push(...body.encounters);
    if (body.encounters.length === 0 || encounters.length >= body.total) return encounters;
  }
}

import os
import requests

BASE = "https://iclinic.phongkhamhieploi.vn/api/integration/v1"


def list_encounters(from_date, to_date, status="all"):
    """Walk through every page."""
    headers = {"Authorization": f"Bearer {os.environ['ICLINIC_API_KEY']}"}
    encounters, page = [], 0
    while True:
        res = requests.get(
            f"{BASE}/encounters",
            headers=headers,
            params={"from": from_date, "to": to_date, "status": status,
                    "page": page, "pageSize": 200},
            timeout=30,
        )
        res.raise_for_status()
        body = res.json()
        encounters += body["encounters"]
        if not body["encounters"] or len(encounters) >= body["total"]:
            return encounters
        page += 1

200 Response

{
  "requestId": "req_7c1f3a",
  "from": "2026-09-14",
  "to": "2026-09-19",
  "page": 0,
  "pageSize": 200,
  "total": 1,
  "encounters": [
    {
      "id": "BA-000123",
      "encounterUuid": "3f0c9a52-6d1b-4e7a-9b1e-2a4c8d5e7f10",
      "patientName": "Nguyễn Văn A",
      "phone": "0900000001",
      "visitDate": "2026-09-19",
      "checkedInAt": "2026-09-19T02:14:05.000Z",
      "completedAt": null,
      "status": "ONGOING",
      "patientType": "OLD",
      "diagnosis": "Tăng huyết áp",
      "icd10Code": "I10",
      "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
      "followUpDate": "2026-09-26",
      "updatedAt": "2026-09-19T03:02:40.000Z"
    }
  ]
}