Skip to main content
The clinik.appointments namespace manages FHIR Appointment resources — scheduled or completed interactions between a patient and a care provider. Use it to book, update, cancel, and search appointments across your scheduling system. Each appointment carries a status that moves through a defined lifecycle from proposed to fulfilled or cancelled.

​
create

Create a new Appointment. The status and patientId fields are required. 
const { data, meta } = await clinik.appointments.create(request: AppointmentCreateRequest): Promise<ApiResponse<Appointment>>
​
status
string
required
Appointment status. Accepted values: proposed, pending, booked, arrived, fulfilled, cancelled, noshow, checked-in, waitlist.
​
patientId
string
required
ID of the patient the appointment is for.
​
practitionerId
string
ID of the assigned practitioner.
​
start
string
Appointment start time in ISO 8601 format.
​
end
string
Appointment end time in ISO 8601 format.
​
minutesDuration
number
Duration in minutes. Used when end is not provided.
​
appointmentType
string
Type of appointment. Common values: routine, walkin, urgent, followup.
​
serviceType
string
The specific service being booked.
​
serviceCategory
string
Broad category of the service.
​
specialty
string
Required clinical specialty for the appointment.
​
reasonCode
string
Coded reason for the appointment.
​
priority
number
Numeric priority from 0 (routine) to 9 (most urgent).
​
description
string
A subject line or brief description of the appointment.
​
comment
string
Additional scheduling comments for internal use.
​
patientInstruction
string
Instructions shown to the patient before the appointment.
​
cancelationReason
string
Reason for cancellation when status is cancelled.

​
Example

const { data: appointment } = await clinik.appointments.create({
  status: 'booked',
  patientId: 'pt_abc123',
  practitionerId: 'prac_def456',
  start: '2025-07-15T10:00:00Z',
  end: '2025-07-15T10:30:00Z',
  appointmentType: 'followup',
  serviceType: 'cardiology-consult',
  reasonCode: 'hypertension-follow-up',
  description: 'Three-month hypertension follow-up',
  patientInstruction: 'Please bring your home blood pressure log.',
});

console.log('Appointment ID:', appointment.id);

​
read

Fetch a single appointment by ID. 
const { data, meta } = await clinik.appointments.read(id: string, options?: ReadOptions): Promise<ApiResponse<Appointment>>

​
update

Partially update an appointment. Useful for status transitions, rescheduling, or adding a cancellation reason. 
const { data, meta } = await clinik.appointments.update(id: string, request: AppointmentUpdateRequest): Promise<ApiResponse<Appointment>>

​
Example: cancel an appointment

await clinik.appointments.update('appt_abc123', {
  status: 'cancelled',
  cancelationReason: 'Patient requested reschedule',
});

​
delete

Permanently delete an appointment record. 
const { data, meta } = await clinik.appointments.delete(id: string): Promise<ApiResponse<void>>
Search appointments with optional filters and cursor pagination. 
const { data, meta } = await clinik.appointments.search(params?: ResourceSearchParams): Promise<ApiResponse<PaginatedResponse<Appointment>>>
​
patientId
string
Filter by patient.
​
practitionerId
string
Filter by assigned practitioner.
​
status
string
Filter by appointment status.
​
dateFrom
string
Return appointments starting on or after this date.
​
dateTo
string
Return appointments starting on or before this date.
​
sort
string
Sort field. Prefix with - for descending order.
​
count
number
Results per page.
​
cursor
string
Pagination cursor from a previous response.

​
Example

const { data } = await clinik.appointments.search({
  patientId: 'pt_abc123',
  status: 'booked',
  dateFrom: '2025-07-01',
  dateTo: '2025-07-31',
  sort: 'date',
});