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

Every EHR integration scope conversation eventually reaches the same question: what data will actually show up once the connection is live. Demographics, medications, and lab results are usually a safe assumption, since these map onto well-defined FHIR resources that most certified vendors expose consistently. Clinical notes are a different story, and teams that assume 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, and that gap is exactly where AI-driven health products get their value and their risk.

This piece covers what an EHR integration actually returns for notes, where the coverage gaps sit, and what de-identification costs when a use case requires it.

What a Typical Pull Actually 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, and 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 unstructured content: the notes a clinician actually wrote, which is where most of the clinical reasoning lives.

How Notes Actually 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 actual content, typically inline as base64-encoded PDF, plain text, or HTML, within the scope of whatever the patient consented to share.

In practice, this means the note usually arrives as an encoded blob rather than 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 Actually Are

Three gaps show up consistently on real integrations, and none of them are edge cases.

The first is completeness against what the patient sees in their own portal. Nothing about a FHIR integration guarantees parity with the patient-facing view. If a source system does not expose a given note type over its API, that note simply does not come through, even if the patient can read it by logging into the portal directly.

The second is API exposure itself. Some EHRs implement DocumentReference and Binary inconsistently, or restrict which document types are queryable. A vendor can be fully FHIR R4 compliant on paper and still leave a meaningful share of its note inventory outside what the API surfaces.

The third is the external reference problem, and it is the one teams are least prepared for. Some records point to a document that lives at an external URL rather than embedding it inline. If the integration cannot reach that URL, or the reference has gone stale, the note is effectively unreachable. This has shown up directly on integration work Momentum has done: dangling external references that pointed to content the pull could not retrieve, with no clean way to resolve them from the data received.

None of this means note coverage is unreliable across the board. In practice a meaningful share of notes does come through cleanly. It means the completeness question has to be scoped explicitly at the start of a project, not assumed.

When De-Identification Enters the Picture

If a use case needs de-identified notes, HIPAA gives two paths, and they are not interchangeable. This sits alongside 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: names, dates more precise than year, geographic subdivisions smaller than a state, and so on. It is mechanically simpler to implement as a rule, but it is blunt, and free-text notes make it hard to apply cleanly. A name or a date can hide anywhere inside a paragraph of narrative text, not just in 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 retain some contextual detail, but it carries more overhead to set up and maintain.

De-identifying notes at scale is not a configuration flag on either path. It means OCR on large PDFs to extract the text, followed by NLP scrubbing to catch identifiers embedded in free text that simple pattern matching misses. This is a genuine build, closer in scope to a small data pipeline than to a compliance checklist item.

For consumer health products where the goal is training or grounding an AI model on user-consented data, the more direct path is often explicit user consent to the specific data use, confirmed as legally sound by counsel, rather than investing in a de-identification pipeline before it is clear the product needs one. Teams that go this route should 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

If clinical notes matter to a product, that has to be an explicit line item at the assessment stage, not an assumption baked into a broader "EHR integration" estimate. This is a different data problem than wearables integration, where the data arrives already structured, but products increasingly need both streams together to build a complete picture of a patient's health. The questions worth asking before a project starts: which note types does the target system actually expose over its API, what format do they arrive in, does the use case need de-identification and if so which path fits, and what happens when a reference points outside the data the pull returns.

Getting these answers early is cheaper than discovering them mid-build. A scoped assessment that treats notes as their own workstream, separate from the structured-field pull, avoids the common failure mode where a team budgets for "EHR integration" as a single line and finds the notes work alone eats the timeline.

Momentum scopes clinical notes coverage explicitly as part of EHR integration assessments, including the connection path that best fits how the notes need to be used. If AI training or grounding is part of the plan, that shapes the recommendation from the purpose-of-use conversation onward, not as an afterthought once the pipeline is built.