Epic Appointment Booking, Cancellation, and Rescheduling: A Developer’s Guide
Technology Blogs

Epic Appointment Booking, Cancellation, and Rescheduling: A Developer’s Guide

Akash Varma
Software Engineer
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

  1. 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.
  2. 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.
  3. 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.
  4. 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].
  5. 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:

  1. Whether a direct change is allowed: for the next step
  2. 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:

CallWhat it doesWhere it’s documented
Appointment.$find (STU3)Finds candidate slots using the organization’s Cadence rulesfhir.epic.com (backend systems; clinicians or administrative users)
Appointment.$book (STU3)Books an appointment returned by $findfhir.epic.com (same user types)
Appointment.Search / Read (Appointments) (R4)Finds a patient’s appointments and visit typefhir.epic.com
Patient.Search / Patient.$match / Patient.Create (R4)Finds or creates the patientfhir.epic.com
Cancel and rescheduleChanges an existing appointmentThe 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

Frequently Asked Questions

Find the patient and their upcoming appointments, check whether the organization allows a direct cancel for that appointment, then send the patient, the appointment identifier and a reason to the cancel web service the organization enables. Epic’s public FHIR catalog has no cancel operation.

Yes. Appointment.$find (STU3) returns candidate slots from rules the organization builds in Cadence, and Appointment.$book (STU3) books one of them for a patient and returns the Appointment resource.

Epic’s public FHIR catalog has no reschedule operation. Reschedules usually run through the organization’s scheduling web services, as a booking that references the original appointment.

Usually because the organization hasn’t built Cadence rules that accept your inputs. Epic notes that $find “requires pre-coordination with the healthcare organization” and that organizations may ignore or require different inputs.

Akash Varma

Akash Varma

Software Engineer

Connect Now

Akash is a full-stack developer with over 3.5 years of experience working with the MERN and MEAN stacks. He is passionate about building scalable applications, improving performance, and creating smooth user experiences. His interests include problem-solving, learning new technologies, and developing solutions that make real impact.

Share This Blog

Read More Similar Blogs

Let’s #Transform Healthcare,# Together.

Partner with us to design, build, and scale digital solutions that drive better outcomes.

Location

Global Tech Teams LLC, 525 Washington Blvd, Industrious at Newport Tower, Jersey City, NJ 07310, United States.

Contact

+1 408 786 5974
contact@mindbowser.com
BOOK A QUICK CONSULTATION

Have a Healthcare Project in Mind?

Let’s discuss your goals, workflows, and next steps in a focused consultation call.

Calendar icon Schedule a Call

Contact form