Scheduling and recurrence

For product owners and partners: Use this page to understand what scheduling workflows the MediKIT API supports today, especially around availability, booking, and patient attendance updates.

For architects and developers: Use this page to understand how Schedule, Slot, Appointment, and AppointmentResponse behave in FHIR R4, and how recurrence affects search results.

The MediKIT API exposes scheduling in FHIR R4 through four related interactions:

Resource / operation	Purpose	Scope	Important behaviour
Schedule	Describes practitioner or resource availability patterns	organisation	Search can return both stored schedules and generated recurrence occurrences
Slot	Describes concrete bookable time windows	organisation	Search supports availability filters, including status=free
Appointment	Describes the patient's booked or proposed appointment	organisation + patient	Search requires at least id or date; date search can expand recurrence
AppointmentResponse	Updates the patient's participation status	organisation + patient	POST-only interaction for attendance updates

Supported scheduling flow

For most booking journeys, use the resources in this order:

1. Search Schedule when you need calendar structure or recurring availability.
2. Search Slot when you need concrete, bookable time windows.
3. Book an appointment with Appointment/$book-slot.
4. Update patient attendance later with AppointmentResponse.

Endpoint map

Use case	Endpoint	Notes
Search schedules	GET /v2/{organizationId}/fhir/R4/Schedule	Supports id, service-category, date
Read schedule by ID	GET /v2/{organizationId}/fhir/R4/Schedule/{id}	Stored schedules only
Search slots	GET /v2/{organizationId}/fhir/R4/Slot	Supports start, schedule, service-category, status=free
Read slot by ID	GET /v2/{organizationId}/fhir/R4/Slot/{id}	Returns one stored slot
Search appointments	GET /v2/{organizationId}/fhir/R4/Patient/{patientId}/Appointment	Requires at least id or date; status is optional
Read appointment by ID	GET /v2/{organizationId}/fhir/R4/Patient/{patientId}/Appointment/{id}	Stored appointments only
Book an appointment	POST /v2/{organizationId}/fhir/R4/Patient/{patientId}/Appointment/$book-slot	Custom FHIR operation using a Parameters payload
Update attendance	POST /v2/{organizationId}/fhir/R4/Patient/{patientId}/AppointmentResponse	POST a FHIR R4 AppointmentResponse

Recurrence: what search can return

The part that matters most for integrators is that recurrence is expanded during search.

Schedule search

Schedule search can return two kinds of results:

Result type	What it is	Can be read by ID?	How to recognise it
Stored schedule	A normal stored schedule resource	Yes	No parent extension
Generated schedule	A concrete occurrence expanded from a recurring parent schedule	No	Includes urn:extension:parent:schedule

Generated schedules are search-only results. They exist to make booking and calendar views work with concrete availability windows instead of only recurrence templates.

When recurrence expansion is used with a date filter, the API derives a date window from that filter:

date input	Effective window
date=2026-06-01 or date=eq2026-06-01	date=ge2026-06-01&date=le2026-06-01 (1 day)
date=ge2026-06-01	date=ge2026-06-01&date=le2026-06-08 (default +7 days)
date=le2026-06-01	date=ge2026-05-25&date=le2026-06-01 (default -7 days)
date=ge2026-06-01&date=le2026-06-30	date=ge2026-06-01&date=le2026-06-30 (explicit range)

Appointment search

Appointment search can also return stored and generated results, but only when you search by date.

Result type	What it is	Can be read by ID?	How to recognise it
Stored appointment	A normal stored appointment resource	Yes	No parent extension
Generated appointment	An occurrence expanded from a recurring parent appointment	No	Includes urn:extension:parent:appointment

Generated appointments are also search-only. Do not treat their IDs as durable identifiers for later read-by-ID calls.

Practical rules for recurrence-aware integrations

• Use search endpoints for calendar views and planning windows.
• Use read-by-ID endpoints only for stored resources.
• Treat parent extensions as the stable link back to the stored recurring resource.
• Always prefer explicit date filters when recurrence matters, so the search window is predictable.

Searching for availability

When to use Schedule

Use Schedule when you need to understand availability patterns, service categories, or recurring planning windows.

Typical filters:

Parameter	Meaning
id	Retrieve a specific stored schedule in search form
service-category	Restrict to a category of care or appointment type
date	Expand or filter schedules for a planning horizon

When to use Slot

Use Slot when you need the concrete time windows a user can actually choose from.

Typical filters:

Parameter	Meaning
start	Lower bound used to derive the slot generation window
schedule	Restrict to one schedule logical ID
service-category	Restrict to slots associated with schedules in that category
status=free	Return only bookable free slots

For booking-style user interfaces, Slot is usually the best resource for the final selection step.

Booking an appointment

The MediKIT API does not support generic POST /Appointment creation. Booking is exposed through the custom FHIR operation Appointment/$book-slot.

The request body must be a FHIR R4 Parameters resource with these parameters:

Parameter	Type	Required	Meaning
start	valueDateTime	Yes	Exact slot start time
schedule	valueString	Yes	Logical ID of the source schedule
practitionerRole	valueString	Yes	Logical ID of the practitioner role for matching
status	valueString	Yes	Appointment status to create
comment	valueString	No	Optional patient comment

Booking succeeds only when a matching slot is still available. If no slot matches, or if availability changed meanwhile, the API returns an OperationOutcome.

Updating patient attendance

Patients can update their participation status by POSTing a FHIR R4 AppointmentResponse resource.

Required fields in the request body:

Field	Meaning
appointment.reference	Reference to the target appointment
actor.reference	Must reference the patient from the path
participantStatus	New patient participation status

This interaction is intended for attendance updates, such as a patient declining an appointment. It is not a generic appointment-edit endpoint.

What is supported and what is not

Supported today	Not supported as a general REST pattern
Search and read for Schedule, Slot, and Appointment	Generic POST /Appointment creation
Recurrence-aware search results for Schedule and Appointment	Generic create/update/delete across scheduling resources
Booking through Appointment/$book-slot	Read-by-ID for generated recurrence occurrences
Attendance updates through AppointmentResponse	Treating generated recurrence IDs as durable identifiers

Related pages

• API Reference — R4
• Authentication and onboarding