Appointments

The iClinic Integration API returns a clinic's appointments, including appointments that patients book themselves through the app or the website.

Description	HTTP request
List appointments	`GET /appointments`
Get an appointment	`GET /appointments/{id}`

scheduledAt is in Coordinated Universal Time (UTC). The clinic stores appointment times as local time (UTC+7). The API converts them to UTC, so you do not need to know the clinic's time zone.
Use status, not the time. REQUESTED is an appointment that a patient requested and that is waiting for confirmation. ERROR marks bad data, so skip it.

List appointments

GET/api/integration/v1/appointments

Returns appointments, including those that patients booked themselves, ordered by last update, oldest first. A cancelled appointment is still returned, with status set to CANCELLED. Only a deleted appointment is returned as a deleted record (tombstone). Requires the appointments:read scope.

Query parameters

Parameter	Description
`updatedSince`string · date-timeoptional	Returns only records whose `updatedAt` is at or after this time. Use an ISO 8601 date-time with a time zone, for example `2026-10-01T00:00:00.000Z`. For how to use it, see Incremental sync.
`cursor`stringoptional	The `nextCursor` value from the previous page, exactly as returned. Omit it on the first page. See Pagination.
`limit`integeroptional	From 1 to 500. Default `200`.

Response 200

A page of appointments: { requestId, appointments, nextCursor }. Each element of appointments has the fields of an appointment, or is a tombstone. If nextCursor is not null, there is a next page.

Errors

Error code	When
`INVALID_UPDATED_SINCE`400	`updatedSince` is not an ISO 8601 date-time with a time zone, or appears more than once.
`INVALID_CURSOR`400	`cursor` is not valid, or was issued by a different endpoint.
`INVALID_LIMIT`400	`limit` is not an integer from 1 to 500.
`UNKNOWN_PARAMETER`400	A parameter that is not listed under “Query parameters”, including one with a misspelled name.
`INSUFFICIENT_SCOPE`403	The API key does not have the `appointments:read` scope.

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

curl

curl -sS "https://iclinic.phongkhamhieploi.vn/api/integration/v1/appointments?limit=200" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /appointments?limit=2

{
  "requestId": "req_7c1f3a",
  "appointments": [
    {
      "id": "a41f9c0e-7d25-4b8a-9c36-0e5b1d7a2f44",
      "code": "LH-20261020-003",
      "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
      "phone": "0900000001",
      "scheduledAt": "2026-10-20T02:30:00.000Z",
      "status": "BOOKED",
      "doctorName": "BS. Trần Thị B",
      "room": "Phòng 2",
      "reason": "Tái khám",
      "createdAt": "2026-10-15T07:00:00.000Z",
      "updatedAt": "2026-10-15T07:00:00.000Z",
      "deletedAt": null
    }
  ],
  "nextCursor": null
}

Get an appointment

GET/api/integration/v1/appointments/{id}

Returns one appointment by id, or a tombstone if the appointment was deleted. Requires the appointments:read scope.

Path parameters

Parameter	Description
`id`stringrequired	The `id` of the appointment: the `id` field of an element returned by List appointments.

Response 200

{ requestId, appointment }. appointment is either an appointment, with the fields listed under “An appointment”, or a tombstone.

An appointment

Field	Meaning
`id`string	Stable ID of the appointment. It never changes. Use it as the deduplication key.
`code`string	The appointment code shown to users. For reference only.
`patientId`string \| null	The `id` of the patient in `/patients`; `null` if the appointment is not linked to a patient record.
`phone`string \| null	Phone number for matching the appointment to a patient when it is not linked to a patient record; `null` if there is none.
`scheduledAt`date-time \| null	Appointment time (UTC); `null` if it cannot be determined. Clinic local time is UTC+7.
`status`enum	`REQUESTED` requested by the patient, waiting for confirmation `BOOKED` confirmed `ARRIVED` the patient has arrived `IN_PROGRESS` examination in progress `FINISHED` examination finished `CANCELLED` cancelled `ERROR` bad data, skip it
`doctorName`string	Name of the doctor in charge; an empty string if no doctor is assigned.
`room`string	Examination room; an empty string if no room is assigned.
`reason`string	Reason for the appointment, as free text that can contain health information; an empty string if there is none.
`createdAt`date-time	When the record was created (UTC).
`updatedAt`date-time	When the record last changed (UTC). Together with `id`, it is the sort key for sync.
`deletedAt`null	Always `null` for a record that still exists.

Deleted record (tombstone)

Field	Meaning
`id`string	The `id` of the deleted appointment.
`deletedAt`date-time	When the record was deleted or merged (UTC). If this field has a value, the record is a tombstone: delete this record on your side.
`updatedAt`date-time	When the record last changed (UTC). Together with `id`, it is the sort key for sync.

Errors

Error code	When
`UNKNOWN_PARAMETER`400	The request has a query parameter. This endpoint accepts only `id` in the path.
`INSUFFICIENT_SCOPE`403	The API key does not have the `appointments:read` scope.
`NOT_FOUND`404	No record has this `id`, or the record belongs to another clinic. Both cases return an identical response.

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

curl

curl -sS "https://iclinic.phongkhamhieploi.vn/api/integration/v1/appointments/$APPOINTMENT_ID" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /appointments/{id}

{
  "requestId": "req_7c1f3a",
  "appointment": {
    "id": "a41f9c0e-7d25-4b8a-9c36-0e5b1d7a2f44",
    "code": "LH-20261020-003",
    "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
    "phone": "0900000001",
    "scheduledAt": "2026-10-20T02:30:00.000Z",
    "status": "BOOKED",
    "doctorName": "BS. Trần Thị B",
    "room": "Phòng 2",
    "reason": "Tái khám",
    "createdAt": "2026-10-15T07:00:00.000Z",
    "updatedAt": "2026-10-15T07:00:00.000Z",
    "deletedAt": null
  }
}

200 Deleted appointment

{
  "requestId": "req_7c1f3a",
  "appointment": {
    "id": "d2b8f6a1-4c97-4e03-b5a8-1f6e9d3c7a20",
    "deletedAt": "2026-10-05T03:00:00.000Z",
    "updatedAt": "2026-10-05T03:00:00.000Z"
  }
}