Skip to main content
Appointments represent scheduled clinical interactions between a patient and a practitioner. The FHIR R4 Appointment resource tracks the time, type, specialty, and current status of each booking. Appointments are distinct from encounters — an appointment is the schedule entry; the encounter is the record of what happened during the visit.

​
Create an appointment

const { data: appt } = await clinik.appointments.create({
  status: 'booked',
  patientId: 'pt_abc123',
  practitionerId: 'prac_def456',
  start: '2025-02-01T14:00:00Z',
  end: '2025-02-01T14:30:00Z',
  minutesDuration: 30,
  appointmentType: 'followup',
  serviceType: 'Cardiology consultation',
  specialty: 'Cardiology',
  reasonCode: 'Blood pressure follow-up',
  description: 'Follow-up visit for hypertension management',
  patientInstruction: 'Please bring your home BP log',
});

​
Status lifecycle

Appointments move through a defined set of statuses from proposal to outcome: 
proposed → pending → booked → checked-in → arrived → fulfilled
                                                    ↘ cancelled / noshow
StatusDescription
proposedSuggested but not confirmed
pendingAwaiting confirmation
bookedConfirmed and scheduled
checked-inPatient has checked in
arrivedPatient is at the facility
fulfilledAppointment completed
cancelledCancelled before completion
noshowPatient did not attend
waitlistOn a waitlist

​
Update an appointment

Update status as the appointment progresses, or reschedule by changing the start and end times: 
// Patient checks in
await clinik.appointments.update('appt_xyz789', {
  status: 'checked-in',
});

// Cancel with a reason
await clinik.appointments.update('appt_xyz789', {
  status: 'cancelled',
  cancelationReason: 'Patient requested reschedule',
});

// Reschedule to a new time
await clinik.appointments.update('appt_xyz789', {
  start: '2025-02-03T10:00:00Z',
  end: '2025-02-03T10:30:00Z',
  comment: 'Rescheduled from Feb 1 per patient request',
});

​
Delete an appointment

await clinik.appointments.delete('appt_xyz789');

​
Search appointments

// Upcoming appointments for a patient
const { data: upcoming } = await clinik.appointments.search({
  patientId: 'pt_abc123',
  status: 'booked',
  dateFrom: new Date().toISOString().split('T')[0],
  sort: 'date',
  count: 10,
});

// All appointments for a practitioner today
const today = new Date().toISOString().split('T')[0];
const { data: schedule } = await clinik.appointments.search({
  dateFrom: today,
  dateTo: today,
  sort: 'date',
});

​
Priority

Appointment priority is an integer from 0–9. Use it to surface urgent bookings in scheduling workflows:
ValueMeaning
0Routine (default)
1–3Low urgency
4–6Medium urgency
7–9High urgency
// Urgent same-day appointment
await clinik.appointments.create({
  status: 'booked',
  patientId: 'pt_abc123',
  practitionerId: 'prac_def456',
  start: '2025-02-01T15:00:00Z',
  end: '2025-02-01T15:30:00Z',
  minutesDuration: 30,
  priority: 8,
  reasonCode: 'Acute chest pain — same day evaluation',
});