Clinical Notes in EHR Integrations: What Actually Comes Through and What Does Not

Every EHR integration scoping conversation reaches the question of which data will show up once the connection is live. Demographics, medications, allergies and lab results are usually a safe assumption, since these map onto well-defined FHIR resources that most certified vendors expose consistently. Teams that assume clinical notes behave like any other structured field tend to find out otherwise partway through a build.

This matters most for products where the notes are the point. A clinical data integration built for population health dashboards can often get by on structured fields alone. One built to train or ground an AI model on real clinical language cannot. The free text in a progress note or a discharge summary carries context that a coded problem list never will. That context is where AI-driven health products get their value and their risk.

This article walks through how notes move through an EHR integration and where coverage breaks down. The last two sections cover de-identification and what to settle at scoping.

What a Typical Pull Returns

A standard patient-access pull touches a predictable set of US Core FHIR resources: Patient for demographics, Encounter, Condition for problems, Observation for labs and vitals, MedicationRequest or MedicationStatement, AllergyIntolerance, Immunization, Procedure, DiagnosticReport and CarePlan. These are the resources USCDI requires certified EHRs to expose. In practice they behave close to how the HL7 standard describes them.

Structured fields are the easy part of the build. Mapping a lab result or a medication entry into your own data model is mechanical work once the auth flow and resource pull are in place. The harder, higher-value part is the notes a clinician wrote, since that is where most of the clinical reasoning lives.

How Notes Move Through the API

Clinical notes surface through two resources working together. DocumentReference carries the metadata: document type, author, date and a pointer to the content. Binary carries the content itself, typically inline as a base64-encoded PDF or HTML file and sometimes as plain text, within the scope of whatever the patient consented to share.

In practice the note usually arrives as an encoded blob instead of clean structured text. A progress note that reads as a paragraph in the clinician's EHR arrives as a PDF or HTML document that has to be decoded and, if the use case needs it, parsed. That parsing step is where a lot of estimates go wrong, because "we get the notes" and "we get usable text from the notes" are two different scopes.

Where the Coverage Gaps Are

Two gaps show up on almost every real integration.

The first is what the source system exposes over its API. Nothing about a FHIR integration guarantees parity with the view the patient gets in their own portal. Some EHRs implement DocumentReference and Binary inconsistently or restrict which document types can be queried. A vendor can be FHIR R4 compliant on paper and still leave a meaningful share of its notes outside the API, even when the patient can read them after logging into the portal.

The second is the external reference problem, which teams are least prepared for. Some records point to a document at an external URL instead of embedding it inline. When the integration cannot reach that URL or the reference has gone stale, the note is out of reach. We have run into dangling external references on our own integration work, where the pull could not retrieve the content and the data received offered no clean way to resolve it.

A meaningful share of notes does come through cleanly in practice. The completeness question still has to be scoped explicitly at the start of a project.

When De-Identification Enters the Picture

If a use case needs de-identified notes, HIPAA gives two paths with different tradeoffs. Both sit inside the broader question of HIPAA compliance for any product handling protected health information, since the identifiers that need scrubbing overlap heavily with what counts as PHI under HIPAA in the first place.

Safe Harbor means removing 18 specified identifiers, including names and dates more precise than the year. It is simpler to implement as a rule. Free-text notes make it hard to apply cleanly, because a name or a date can sit anywhere inside a paragraph of narrative text instead of a labeled field.

Expert Determination takes a different route. A qualified statistician certifies that re-identification risk is very small given the specific dataset and its intended use. It is more flexible than Safe Harbor, particularly for datasets that need to keep some contextual detail, but it carries more overhead to set up and maintain.

On either path, de-identifying notes at scale means OCR on large PDFs to extract the text, followed by NLP scrubbing to catch identifiers in free text that simple pattern matching misses. The scope is closer to a small data pipeline than to a compliance checklist item.

For consumer health products that train or ground an AI model on user-consented data, the more direct path is often explicit user consent to the specific data use, confirmed by counsel. That decision usually comes before any investment in a de-identification pipeline the product may not need. Read it alongside the purpose-of-use question, since consent and legal basis are two sides of the same decision.

What This Means for Scoping a Clinical Data Integration

If clinical notes matter to a product, they need their own line item at the assessment stage instead of sitting inside a broader "EHR integration" estimate. Wearables integration is a different data problem, since that data arrives already structured, yet products increasingly need both streams together for a complete picture of a patient's health.

Four questions are worth answering before a project starts. Which note types does the target system expose over its API and in what format? Does the use case need de-identification? Which connection path suits how the notes will be used? What happens when a reference points outside the data the pull returns?

Getting these answers early costs less than discovering them mid-build. A scoped assessment that treats notes as their own workstream avoids the case where a team budgets for "EHR integration" as one line and then finds the notes work alone eats the timeline.

Momentum scopes clinical notes coverage explicitly in our EHR integration assessments, together with the connection path that best fits how the notes will be used. If AI training or grounding is part of the plan, the purpose-of-use conversation shapes the recommendation from the start.