Epic integration that supports read and limited write: how write-back works

Reading from Epic is predictable. Writing back is a set of specific Create and Update APIs, each with its own rules, and every health system decides which of them your app may use.

In short

  • An Epic integration with read and limited write means your app reads USCDI data through Epic's FHIR R4 APIs and writes back only through the specific Create or Update APIs Epic lists for each resource, such as vital signs, flowsheets, problems, clinical notes and patient-entered questionnaire answers.
  • Epic's documentation says flowsheet data is often filed through Observation.Create, that patient-facing filing needs an app with Patients as the primary user type and OAuth 2.0, and that each vital reading is posted as its own call.
  • Each health system enables the APIs on the app's client ID and decides where your data lands, so a write-back plan is a list of APIs per feature, agreed customer by customer, with a clear plan for failed writes.

An Epic integration that supports read and limited write reads patient data through Epic's standard FHIR R4 APIs and writes back only through the specific Create or Update APIs Epic publishes for each kind of data. Read access is broad and predictable. Write access is narrow, defined API by API, and switched on by each health system for your app.

This guide is for product and engineering leads planning a chronic care, remote monitoring, intake or documentation product that needs to put something back into the chart. Everything about Epic below comes from Epic's developer sites, linked at the end. Epic changes these pages often, so check the listing for each API before you design around it.

Why is reading from Epic easier than writing?

Reading rests on a federal floor. EHRs certified to ONC's §170.315(g)(10) criterion must answer requests for a single patient's data and for groups of patients using FHIR R4, US Core and SMART App Launch, with USCDI as the data set. That is why the read side looks much the same from one Epic customer to the next: medications, problems, allergies, lab results, vitals and the other USCDI data classes your scopes allow.

Writing has no such floor. The certification criterion is about access to data, so each write API is Epic's own product decision, and each health system decides whether to allow it. Writing also carries clinical risk the read side does not. A wrong value filed into the chart can be acted on, so expect a health system to review each write more closely than the reads.

Which Epic APIs can write data back?

Epic on FHIR groups its APIs by interaction: Read, Search, Create, Update and a few operations. At the time of writing, the Create and Update entries in Epic's listing include these, among others:

  • Observation: Vital Signs (Create, R4 and STU3), Flowsheets (Create, R4), and Lines, Drains, Airways (Create and Update).
  • Condition: Problems (Create, R4 and STU3).
  • DocumentReference: Clinical Notes (Create, R4 and STU3) and Document Information (Create and Update, R4).
  • AllergyIntolerance: Patient Chart (Create, R4).
  • QuestionnaireResponse: Patient-Entered (Create, R4).
  • Patient: Demographics (Create, R4 and STU3), and Communication: Community Resource (Create, R4).

Each entry has its own documentation page with required fields, supported codes and the user types it allows. Read that page for every write your product needs. Two APIs that look alike in the list can behave quite differently once you open them.

How does filing a reading to a flowsheet work?

Flowsheets are where many measurements live in Epic, and they are the most common write target for monitoring products. Epic's documentation says an Observation.Create API is often used to file data to flowsheets. For remote patient monitoring, Epic states that Observation.Create must be added to an app with Patients as the primary user type, that the calls must be authenticated with OAuth 2.0, and that vital readings must be posted individually, each as its own Observation.Create call.

Epic's API change log adds two details worth knowing. The Observation (Flowsheets) R4 sub-resource now handles non-vital-sign flowsheet data, and Epic notes a Flowsheets sub-resource starting in its November 2026 version. In practice that means vital signs and other flowsheet rows can follow different APIs, and the customer's Epic version decides what is available.

  • Map every value you file to the flowsheet row the customer chooses. Row choices are local configuration, so the health system supplies them. Epic's sandbox will not have them.
  • Post one reading per call and keep your own record of which call filed which reading.
  • Expect the customer to decide who reviews incoming readings and where clinicians see them.

How do patient-facing writes stay authorized?

A monitoring app files readings long after the patient last signed in. Epic's remote monitoring material describes an account-linking flow: the patient opens MyChart, launches your linking page through an embedded launch, and your app receives an access token, a refresh token and the patient's FHIR ID. Epic says the app must be set up with JWT authentication to receive a refresh token, so patients do not have to log in each time a reading is filed.

Epic's guidance also says that for a patient-facing app using JWTs, the Require Refresh Tokens setting must be checked so you can upload your public key, and that you will upload non-production and production public keys for each customer. Plan key management with the rest of the integration work, because every new customer adds keys to track.

How do you write clinical notes into Epic?

Epic describes two routes for notes. Your app can write PDF or RTF note content through Incoming Transcriptions, or plain text note content through the DocumentReference FHIR API. The Clinical Notes entry under DocumentReference is the FHIR route most documentation and intake products start with.

Decide early what a note from your product should be. A plain text note is searchable and easy to review. A PDF keeps layout, which matters for forms and reports. Either way, the health system decides the note type, who signs it, and whether it needs review before it becomes part of the record.

What do SMART scopes say about write access?

SMART App Launch 2.x scopes spell out permissions with the letters c, r, u, d and s for create, read, update, delete and search. A scope such as patient/Observation.rs allows reading and searching a patient's observations. Adding c allows creating them. In the older v1 syntax, .read maps to .rs and .write maps to .cud.

Epic's documentation notes that SMART scopes come back in the scope parameter of the token response and that SMART v2 scopes use this CRUDS syntax. The SMART guide warns that granted scopes may differ from requested ones, and it recommends that apps check what was granted. For a write-back product, that check decides whether the write button is shown at all.

  • Request read and write scopes separately and only for the resources each feature needs.
  • Check the granted scopes after every token exchange and turn off features that lost their scope.
  • Register only the APIs you will call in production. Epic's developer guide asks for exactly that, and every extra API is another question from the customer's reviewers.

What happens when a write fails?

Writes fail for ordinary reasons: an expired token, a key that has not synced, a flowsheet row the customer has not configured, or a value that fails validation. Epic's documentation notes that after re-uploading a public key you need to wait for the change to sync. Your design has to assume these failures and make them visible.

  • Queue every write with its payload, the patient, the target API and a status.
  • Retry with backoff for transient errors and stop for validation errors that need a person.
  • Show the patient or user a clear pending state when data has not reached the care team yet.
  • Give the customer's support team a way to see failed writes for their own patients only.
  • Never write the same reading twice. Keep an identifier for each reading so a retry does not create a duplicate.

How do you agree on write-back with each health system?

Epic's developer guide puts the customer in charge of go-live: it requests the app's client ID for its environment, enables any customer-specific keys, and tests with you. For write-back, bring a short document to that conversation.

  • Each write your product makes, the Epic API it uses, and the feature that needs it.
  • Where the data should land: flowsheet rows, note types, problem list entries.
  • Who reviews incoming data and what happens if nobody does.
  • How you handle failures, retries and duplicates.
  • Which writes can wait for a second phase if the customer wants to start with read only.

Starting read only and adding writes later is a reasonable plan. It lets the customer see your product working with their data before they allow it to change anything.

How do you test write-back before go-live?

Epic's sandbox lets you test APIs against example data, try calls without code and test app launch. Use it to prove each write works end to end. Then plan time in each customer's non-production environment, because flowsheet rows, note types and enabled APIs are configured there and nowhere else.

Keep a written test for every write: the input, the expected result in the chart, and who on the customer side confirmed it. That record answers most of what a reviewer will ask before production.

We have shipped Epic and athenahealth integrations, and for any vendor platform we work from the vendor's documentation and sandbox. If you are planning write-back to Epic and want to know which APIs, scopes and customer decisions your product needs, talk to one of our engineers. Our free five-day technical audit ends with a written report you can take to your first health system.