Therapy plans

The iClinic Integration API returns the therapy plans of a clinic's patients: how many sessions are done out of the total, and how much money has been collected.

Description	HTTP request
List therapy plans	`GET /therapy-plans`
Get a therapy plan	`GET /therapy-plans/{id}`

The status is derived the same way as on the clinic's own screen: COMPLETED when all sessions are done, IN_PROGRESS when at least one session is done, CANCELLED when the plan is cancelled.

List therapy plans

GET/api/integration/v1/therapy-plans

Returns therapy plans ordered by last update, oldest first. completedSessions and paidAmount change when a session is recorded or a payment is collected, and updatedAt changes too. Requires the therapy: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 therapy plans: { requestId, therapyPlans, nextCursor }. Each element of therapyPlans has the fields of a therapy plan, or is a deleted record (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 `therapy:read` scope.

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

curl

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

200 GET /therapy-plans?limit=2

{
  "requestId": "req_7c1f3a",
  "therapyPlans": [
    {
      "id": "7b2e4d90-1a63-4c85-b7f0-3d9a6c1e8b52",
      "code": "LT-20261001-001",
      "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
      "name": "Liệu trình châm cứu 10 buổi",
      "sessionCount": 10,
      "completedSessions": 4,
      "status": "IN_PROGRESS",
      "totalPrice": 3500000,
      "paidAmount": 3500000,
      "createdAt": "2026-10-01T02:00:00.000Z",
      "updatedAt": "2026-10-12T07:30:00.000Z",
      "deletedAt": null
    }
  ],
  "nextCursor": null
}

Get a therapy plan

GET/api/integration/v1/therapy-plans/{id}

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

Path parameters

Parameter	Description
`id`stringrequired	The `id` of the therapy plan: the `id` field of an element returned by List therapy plans.

Response 200

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

A therapy plan

Field	Meaning
`id`string	Stable ID of the therapy plan. It never changes. Use it as the deduplication key.
`code`string	The therapy plan code shown to users. For reference only.
`patientId`string \| null	The `id` of the patient in `/patients`; `null` if the therapy plan is not linked to a patient record.
`name`string	Name of the therapy plan.
`sessionCount`integer	Total number of sessions in the therapy plan.
`completedSessions`integer	Number of sessions already done.
`status`enum	`NEW` no session done yet `IN_PROGRESS` in progress `COMPLETED` all sessions done `CANCELLED` cancelled
`totalPrice`integer	Total price of the therapy plan, in Vietnamese dong (VND).
`paidAmount`integer	Amount collected for the therapy plan, in VND. It decreases when a payment receipt is refunded.
`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 deleted therapy plan.
`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 `therapy: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/therapy-plans/$THERAPY_PLAN_ID" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /therapy-plans/{id}

{
  "requestId": "req_7c1f3a",
  "therapyPlan": {
    "id": "7b2e4d90-1a63-4c85-b7f0-3d9a6c1e8b52",
    "code": "LT-20261001-001",
    "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
    "name": "Liệu trình châm cứu 10 buổi",
    "sessionCount": 10,
    "completedSessions": 4,
    "status": "IN_PROGRESS",
    "totalPrice": 3500000,
    "paidAmount": 3500000,
    "createdAt": "2026-10-01T02:00:00.000Z",
    "updatedAt": "2026-10-12T07:30:00.000Z",
    "deletedAt": null
  }
}

200 Deleted therapy plan

{
  "requestId": "req_7c1f3a",
  "therapyPlan": {
    "id": "9e3a5c17-2d48-4f60-a1b9-7c0d6e8f4b35",
    "deletedAt": "2026-10-05T03:00:00.000Z",
    "updatedAt": "2026-10-05T03:00:00.000Z"
  }
}