TL;DR
Epic publishes FHIR operations to find and book appointments (Appointment.$find and $book, STU3) and to read and search them (R4). $find only works after the organization builds its scheduling rules in Cadence. Cancelling and rescheduling usually run through the scheduling web services the organization enables for your app, under your client ID. Check the response body as well as the status code, check whether a direct cancel is allowed, and pass slot data back unchanged.
A Bit of Context First
Scheduling an appointment doesn’t sound like a hard problem. The patient picks a time, and the doctor shows up. But once you start building with Epic, you realize pretty quickly that there’s a lot going on behind the scenes.
It’s one of the biggest EHR systems, and it’s quite particular about how things need to be done. You have to follow a certain sequence and stick to the expected formats, and even small mistakes can cause failures without clear errors.
Most of the time, you only figure this out after spending hours debugging something minor, like an extra space in an ID.
This post walks through all three flows (booking, cancelling, and rescheduling) and tries to explain not just what to call them but why things are set up the way they are. If you’re new to Epic integrations or just picking this up mid-project, hopefully it saves you some real time.
A Few Things to Understand Upfront
- FHIR Standards: FHIR is the standard way healthcare systems exchange data with each other. Epic supports FHIR R4 for certain APIs, enabling data exchange with other health systems. For scheduling, Epic publishes FHIR operations to find and book appointments ($find and $book) and to read and search them [Epic FHIR catalog]. Cancelling and rescheduling usually run through the scheduling web services your Epic organization enables and documents for your app, so most workflows mix FHIR and non-FHIR calls.
- Appointment Definition: A FHIR appointment is a structured record containing patient, provider, time, location, and status information (booked, cancelled, arrived). This data structure serves queries about appointment history and rescheduling details.
- Slot Concept: A slot represents a time block a provider designated as available. Epic enforces using pre-designated slots rather than arbitrary times. Attempting to book outside existing slots results in rejection.
- Authentication: every call runs under your app’s client ID. Epic: “All web services require a client ID to identify the calling application as part of the Epic authorization framework” ([open.epic](https://open.epic.com/Interface/WebServices)). The FHIR scheduling operations support backend-system and clinician or administrative-user OAuth 2.0 contexts [Epic, Appointment.$find].
- ID Types: an Epic patient carries several identifiers (medical record number, enterprise ID, IDs from outside systems), and the type codes vary between Epic organizations. Confirm them with the organization’s Epic team before development begins.
Flow 1: Booking an Appointment
Step 1: Find or Create the Patient
New: Patient lookup begins every workflow. Search with Patient.Search (Demographics) (R4), use Patient.$match (R4) when you hold several demographics, or use Epic’s Patient Lookup web service, which open.epic lists publicly [Epic FHIR catalog].
When the patient doesn’t exist, create the record with Patient.Create (Demographics) (R4). Epic’s own booking workflow does the same: “For new patients, the app would perform a Patient.Create interaction” before booking [Epic, Appointment.$book].
Test patient creation in Epic’s sandbox first, then confirm with the organization which fields its registration rules require.
Step 2: Match the Reason for Visit
Determine the appropriate visit type, department, and provider based on the patient’s presenting complaint. Patients express concerns conversationally (“My knee’s been bothering me for a week”) rather than in Epic terminology.
Basic keyword matching between patient input and available visit type names handles most scenarios. Default to the most general visit type when nothing matches rather than rejecting the patient.
Step 3: Find Available Days
API: Appointment.$find (STU3)
Send the patient’s criteria: when, which specialty or visit type, the patient’s time zone, and optional preferences. Epic applies rules the organization builds in [Cadence] and returns candidate slots that don’t overlap. $find needs that pre-coordination: “The organization must build out specific rules in the Epic Cadence scheduling system” [Epic, Appointment.$find].
Step 4: Book the Appointment
API: Appointment.$book (STU3)
Send the patient ID and the appointment ID the user picked from the $find results, plus an optional note. $book returns the booked Appointment resource [Epic, Appointment.$book].
A gotcha worth testing for: a call can return HTTP 200 OK and still carry an error in the response body (in FHIR, an OperationOutcome).
Always read the response body after a booking call, for example to catch a slot someone else took between find and book. Successful HTTP status codes don't guarantee successful bookings.Talk to our Epic integration team
Flow 2: Cancelling an Appointment
Step 1: Find the Patient
Find the patient the same way as in the booking flow.
Step 2: Pull Their Appointments
API: Appointment.Search (Appointments) (R4), plus the scheduling web service your organization enables for cancellations. Keep two things for each upcoming appointment:
- The appointment identifier: what your cancel call needs
- Whether a direct cancel is allowed: the organization decides which appointments a patient may cancel without calling the clinic
Step 3: Check Whether a Direct Cancel Is Allowed
This is the step developers miss most. Check the organization’s setting for the appointment before cancelling:
- Allowed: proceed with the cancellation
- Not allowed: stop, and tell the patient to contact the clinic
Cancelling anyway fails or leaves the appointment in an unexpected state.
Step 4: Cancel the Appointment
API: the cancel web service your Epic organization enables (Epic’s public FHIR catalog has no cancel operation)
Send the patient, the appointment identifier and a cancellation reason. Don’t send a blank reason. If your interface doesn’t collect reasons, default to something like “Patient requested cancellation.” Trim spaces from IDs before sending, as legacy data sometimes carries formatting that causes silent failures.
Flow 3: Rescheduling an Appointment
Rescheduling involves more API calls and value propagation, requiring careful tracking of earlier responses.
Step 1: Find the Patient
Find the patient the same way as in the booking flow.
Step 2: Get Their Appointments
API: Appointment.Search (Appointments) (R4), plus your organization’s scheduling web service for change details. Keep two things:
- Whether a direct change is allowed: for the next step
- The original appointment’s identifier, exactly as your scheduling service returns it: save it unchanged for the final step.
Step 3: Check Whether a Direct Change Is Allowed
If not, tell the patient that online rescheduling is unavailable and give the clinic’s contact details.
Step 4: Get the Visit Type from FHIR
API: Appointment.Search (Appointments) (R4)
Look up the appointment and read serviceType, the visit type. Epic’s Appointment resource carries it there (Epic’s $book example returns “Physical Therapy Visit” in serviceType, [Epic]. Use that value when you look for new slots.
Step 5: Find Open Slots for the New Time
API: Appointment.$find (STU3), or the slot web service your organization enables
Use the provider, department, and visit type retrieved above. Epic returns available slots with date, time, and duration information.
A critical requirement: when Epic returns the slot data, save the whole object exactly as-is. Don’t change anything or extract only parts of it. The full slot object must be sent unchanged in the next step, or Epic will reject the request.
Step 6: Complete the Reschedule
API: the scheduling web service your Epic organization enables for reschedules
Epic’s public FHIR catalog has no reschedule operation. Check your organization’s documentation for how a reschedule references the original appointment, using the identifier you saved in Step 2.
That reference is what makes it a reschedule rather than a second booking. Confirm in testing that the original appointment is released when the new one is booked.
Slot data can be nested to carry pooled availability, split appointments and several providers. Even in simple cases, pass it back exactly as the find call returned it.
Authentication Quick Reference
Every call runs under your app’s client ID within Epic’s authorization framework [open.epic]. What Epic publishes for the scheduling calls:
| Call | What it does | Where it’s documented |
|---|---|---|
| Appointment.$find (STU3) | Finds candidate slots using the organization’s Cadence rules | fhir.epic.com (backend systems; clinicians or administrative users) |
| Appointment.$book (STU3) | Books an appointment returned by $find | fhir.epic.com (same user types) |
| Appointment.Search / Read (Appointments) (R4) | Finds a patient’s appointments and visit type | fhir.epic.com |
| Patient.Search / Patient.$match / Patient.Create (R4) | Finds or creates the patient | fhir.epic.com |
| Cancel and reschedule | Changes an existing appointment | The scheduling web services your Epic organization enables (client ID required; open.epic) |
Common Mistakes Worth Knowing About
- Booking without $find: Epic’s $book only books an appointment returned by $find.
- Skipping the direct-cancel check: run it before both cancelling and rescheduling.
- Trusting HTTP 200 as success: Epic returns business errors within 200 responses. Always examine response bodies.
- Calling $find before the organization builds its rules: $find needs the organization’s Cadence scheduling rules in place first.
- Modifying slot data: pass it back exactly as received.
- Rebuilding identifiers: store appointment identifiers exactly as Epic returns them, and never parse or reconstruct them.
- Blank cancellation reasons: Epic rejects these. Maintain sensible defaults.
- Timezone mismatches: Epic interprets time strings using its own configured timezone. If users occupy different zones, convert before API calls. This oversight during development becomes a production issue.
Conclusion
Epic appointment scheduling runs in [Epic Cadence](https://www.mindbowser.com/epic-cadence-a-guide-for-healthcare-scheduling/), one of the [Epic modules], and integrations with it depend on calling things in the right order. Booking, cancellation, and rescheduling all begin with patient lookup but diverge significantly in subsequent steps.
Booking requires response body validation rather than relying solely on HTTP status codes. Cancellation needs the direct-cancel check first, because the organization may not allow direct cancellation for some appointments.
Rescheduling combines FHIR and non-FHIR APIs in the most complex workflow. Keep the original appointment identifier, use the visit type from FHIR, and pass slot data back unchanged. Getting these details right makes appointments more reliable for patients and care teams.
Where to go next
• Epic Cadence: how Epic scheduling works
• Epic integration services: what Mindbowser builds around Epic
• ConnectHealth, our EHR integration product: HL7 v2, FHIR and X12 in, one consistent format out, running in your own cloud
• Talk to our Epic integration team








BLOGS
NEWSROOM
CASE STUDIES
WEBINARS
PODCASTS
ASSET HUB
EVENT CALENDAR 


















