Pre-appointments

A pre-appointment is the central entity of the check-in flow: one scheduled visit, captured before care. It holds the beneficiary, the payer, the doctor/specialty, the appointment date, and the charges (the procedures/products expected for the visit).

It is created in one of two ways — its source:

Source	How	Who
HIS_INBOUND	Pushed automatically from your Hospital Information System via POST /v1/checkin/appointments/his-inbound	Your HIS integration
MANUAL	Created by hand via POST /v1/checkin/appointments	The reception/admissions user (fallback)

Lifecycle

A pre-appointment moves through a small set of statuses. The transition that matters for integrators is PENDING → CONFIRMED, done at check-in.

No hard blocks

Confirming a pre-appointment never fails because of missing or AI-rejected documents. The reception user is expected to be warned beforehand (see Documents), but they can always confirm and let the patient through. The only reason POST /{id}/confirm fails is a status conflict — the appointment isn't in PENDING (returns 409).

• Delete is a soft-delete: DELETE /{id} disables the record so it stops appearing in listings, but it does not change status — a deleted pre-appointment stays PENDING. It is only allowed on PENDING appointments with source MANUAL; anything else returns 400.
• CANCELLED and COMPLETED are reached by updating the status explicitly with PUT /{id}, not by deleting. Both are terminal: once there, no further transition is accepted.
• Confirm is treated as an update — it's a state change, equivalent to a PUT with status = CONFIRMED, and needs the same permission.

Charges

Each pre-appointment carries a list of charges — the procedures/products expected. A charge is identified by the provider's own product code:

{
  "provider_product_code": "PROC001",
  "provider_product_name": "Electrocardiogram (ECG)",
  "quantity": 1
}

provider_product_code is the key that ties everything together: it's how required documents are matched to a charge, and how uploaded documents complete the right placeholders.

Endpoints

Operation	Endpoint
Create (manual)	POST /v1/checkin/appointments
Create/merge (HIS)	POST /v1/checkin/appointments/his-inbound
Update (HIS)	PUT /v1/checkin/appointments/his-inbound/{external_appointment_id}
Delete (HIS)	DELETE /v1/checkin/appointments/his-inbound/{external_appointment_id}
Update (manual)	PUT /v1/checkin/appointments/{id}
Get by ID	GET /v1/checkin/appointments/{id}
List (paginated + filters)	GET /v1/checkin/appointments
Filter options	GET /v1/checkin/appointments/filter-options
Confirm	POST /v1/checkin/appointments/{id}/confirm
Delete (soft, manual)	DELETE /v1/checkin/appointments/{id}

See the full request/response schemas and try them live in the API Reference.

Listing and filters

GET /v1/checkin/appointments is paginated (default 20 per page, sorted by appointment_date descending) and accepts filters. GET .../filter-options returns the payers, doctors and specialties from the provider's catalogs to populate the filter combos in a UI.

Everything is scoped to the authenticated provider — you only ever see your own pre-appointments.