Patients

The patients endpoints of the iClinic Integration API return the minimal administrative record of a patient: enough to identify a person and call them. They do not return a national ID number (CCCD), email, address, allergies or full date of birth.

Description	HTTP request
List patients	`GET /patients`
Get a patient	`GET /patients/{id}`

Merged records. When a clinic merges two duplicate records, the merged record becomes a deleted record (tombstone) with mergedIntoId. Its appointments, receipts and therapy plans move to the surviving record, and they also get a new updatedAt.
Phone number is null when the clinic has no number.

List patients

GET/api/integration/v1/patients

Returns the clinic's patients, ordered by last update, oldest first. A record that was merged into another record is still listed, as a tombstone with mergedIntoId. Requires the patients: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 patients: { requestId, patients, nextCursor }. Each element of patients has the fields of a patient, 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 `patients:read` scope.

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

curl

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

200 GET /patients?limit=2

{
  "requestId": "req_7c1f3a",
  "patients": [
    {
      "id": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
      "code": "BN-000412",
      "name": "Nguyễn Văn A",
      "phone": "0900000001",
      "gender": "MALE",
      "birthYear": 1984,
      "patientType": "OLD",
      "status": "ACTIVE",
      "registeredDate": "2026-03-02",
      "createdAt": "2026-03-02T01:30:00.000Z",
      "updatedAt": "2026-10-04T08:12:45.120Z",
      "deletedAt": null
    },
    {
      "id": "c9a1d7e2-0b34-4c6f-8a51-6e7f3b2d9c08",
      "deletedAt": "2026-10-05T03:00:00.000Z",
      "updatedAt": "2026-10-05T03:00:00.000Z",
      "mergedIntoId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10"
    }
  ],
  "nextCursor": "djF8cGF0aWVudHN8MjAyNi0xMC0wNVQwMzowMDowMC4wMDBafGM5YTFkN2UyLTBiMzQtNGM2Zi04YTUxLTZlN2YzYjJkOWMwOA"
}

Get a patient

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

Returns one patient by id, or a tombstone if the record was merged. Requires the patients:read scope.

Path parameters

Parameter	Description
`id`stringrequired	The patient's `id`: the `id` field of an element returned by List patients.

Response 200

{ requestId, patient }. patient is either a patient, with the fields listed under “A patient”, or a tombstone.

A patient

Field	Meaning
`id`string	Stable ID of the patient. It never changes. Use it as the deduplication key.
`code`string	The record code shown to users. For reference only.
`name`string	Full name of the patient.
`phone`string \| null	Phone number in the form `0…`; `null` if the clinic has no number.
`gender`enum	`MALE` male `FEMALE` female `OTHER` other `UNKNOWN` unknown
`birthYear`integer \| null	Year of birth; `null` if it is not recorded. The full date of birth is never returned.
`patientType`enum	`NEW` new patient `OLD` returning patient `RE_EXAMINATION` scheduled follow-up
`status`enum	`ACTIVE` in use `INACTIVE` the clinic has deactivated this record
`registeredDate`date	Date the record was registered (clinic local time), `YYYY-MM-DD`. This is not the date of the first encounter: a record can be registered before the first visit.
`createdAt`date-time	When the record was created, in Coordinated Universal Time (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 merged record.
`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.
`mergedIntoId`string \| null	The `id` of the record that remains after the merge; `null` if the record was deleted without a merge. The appointments, receipts and therapy plans of the old record have been moved to this record.

Errors

Error code	When
`UNKNOWN_PARAMETER`400	The request has a query parameter. This endpoint accepts only the `id` in the path.
`INSUFFICIENT_SCOPE`403	The API key does not have the `patients: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/patients/$PATIENT_ID" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /patients/{id}

{
  "requestId": "req_7c1f3a",
  "patient": {
    "id": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
    "code": "BN-000412",
    "name": "Nguyễn Văn A",
    "phone": "0900000001",
    "gender": "MALE",
    "birthYear": 1984,
    "patientType": "OLD",
    "status": "ACTIVE",
    "registeredDate": "2026-03-02",
    "createdAt": "2026-03-02T01:30:00.000Z",
    "updatedAt": "2026-10-04T08:12:45.120Z",
    "deletedAt": null
  }
}

200 Merged record

{
  "requestId": "req_7c1f3a",
  "patient": {
    "id": "c9a1d7e2-0b34-4c6f-8a51-6e7f3b2d9c08",
    "deletedAt": "2026-10-05T03:00:00.000Z",
    "updatedAt": "2026-10-05T03:00:00.000Z",
    "mergedIntoId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10"
  }
}