eClinicalWorks Reminders: Ask /metadata First

Every conformant FHIR server exposes a /metadata endpoint that returns a CapabilityStatement: a machine-readable list of the resources it supports, which interactions it allows on each (read, search-type, create, update), and which search parameters it accepts.

For eCW work this endpoint is not a nicety. It is the first call you make against any new practice instance. Pull /metadata, save it, and read it before you write a line of integration code. It tells you in a few seconds what would otherwise take a week of trial-and-error tickets.

Store it. Practices get upgraded, and a capability statement from six months ago is a historical document, not a specification. Re-pull it on a schedule and diff it. A resource silently appearing or disappearing is the kind of change that breaks a reminder job at 6am with no deploy on your side to blame.

This is the detail that most often sends teams down the wrong path. eClinicalWorks runs two separate developer programs, and they serve different kinds of applications.

The eCW FHIR Developer Portal covers provider-centric applications: SMART on FHIR apps a clinician launches from inside the chart, and backend or bulk service applications that pull data on a schedule with no user present.

The healow Developer Portal covers patient-facing applications, which per eCW's own documentation include scheduling platforms.

If you're building appointment reminders, read that split carefully before registering anywhere. Reminders are usually a backend workflow, which points at the provider portal. But if your product also lets the patient reschedule or self-book from the reminder, the feature that actually recovers the appointment, you're in patient-facing territory, and eCW directs creating encounters through healow instead.

Plenty of teams register in one program, build for a month, and discover the write path they need lives in the other. Registration and approval are not instant, so this is an expensive mistake rather than an annoying one.

Assume for planning purposes that your first eCW integration is read-only, because that's the shape of the free tier rather than an accident of your setup. The openly available API is a read path; write access, the part that lets you change anything in the chart or the calendar, sits behind access the practice contracts directly with eCW.

That detail reorders the project. The blocker isn't your registration, and it isn't something you can escalate as a vendor: the customer signs for it. Which means the earliest useful conversation isn't with eCW's developer portal, it's with the practice, asking whether their contract already includes write access and who at eCW owns that line. Teams routinely discover the answer three weeks into building.

So design for read-only, and treat write as an upgrade path rather than a prerequisite.

A read-only reminder system works like this. Poll for upcoming appointments on a window, typically the next few days, and compare against what you sent last run. New appointment in the window with no reminder sent: send one. Appointment that disappeared or changed status since last run: treat it as cancelled or moved and stop the sequence. The patient's response comes back to you, not to eCW, and a human reconciles anything that needs to change in the chart.

That last sentence is the compromise. It means someone at the practice is retyping confirmations, and practices will ask you to remove that step. Be straight with them about what removing it requires: write access, which requires the healow portal, which requires a separate approval.

A CapabilityStatement is a large document and most of it is irrelevant to a reminder job. Four fields matter.

• The rest.resource list. Is Appointment in it at all? If not, nothing below matters and you have a scoping conversation to have.
• The interaction codes on that resource. read alone means you can fetch an appointment you already know the id of, which is useless for discovery. You need search-type to find appointments by date. The difference between those two codes is the difference between a working product and a demo.
• The searchParam list on the resource. A date search parameter is the minimum. Without one you cannot ask for appointments in the next 48 hours, and polling degrades into pulling everything and filtering client-side, which works at ten patients and falls over at ten thousand.
• The fhirVersion at the top. R4 and STU3 name things differently, and code written against one fails in ways that look like permission errors rather than version errors. Reading that field first saves an afternoon of misdiagnosis.

Everything else in the document can wait until you need it.

Without webhooks, polling frequency is a direct trade between freshness and load, and both failure modes are visible to the patient.

Poll too slowly and you send a reminder for an appointment that was cancelled an hour ago. That's a support call, and it damages trust in every message you send after it.

Poll too fast and you're generating load against a practice's production system for very little marginal information. An appointment booked three days out does not change minute to minute.

The shape that works is uneven rather than uniform. Poll the near window often, the next 24 to 48 hours, where changes are frequent and consequential. Poll the far window rarely, because a change to an appointment nine days out will be caught long before the reminder for it goes anywhere.

Put a final freshness check immediately before the message sends. Re-read that one appointment, confirm it still exists and still holds the status you expect, then send. One extra read per message is cheap. A reminder for a cancelled visit is not.

We have an eClinicalWorks port that handles patient demographics and clinical resources: allergies, conditions, medications. It does not include scheduling. So the reminder architecture above is a design derived from eCW's published API structure and from patterns that hold across FHIR deployments generally, not a description of an eCW appointment integration we run.

Anything specific to your target practice, which resources, which parameters, which version, comes from that practice's /metadata. Trust it over this page and over any datasheet.