Skip to content
Engineering guide · facts checked 13 November 2026

AI scribe EHR integration: from approved draft to signed note in the chart

For ambient-scribe start-ups and the practices that buy from them: which write-back path each EHR accepts, how the draft-then-sign step works, and how to stop wrong-patient notes, duplicates and silent failures before a clinician finds them.

Doctor in a white coat with a stethoscope holding a smartphone in both hands
At a glance
  • Three write-back routesFHIR DocumentReference, HL7 MDM^T02, vendor APIs
  • Signing decides the routeSome EHRs accept only final notes over FHIR
  • One note, one identifierConditional create and TXA-12 stop duplicates
  • Nothing fails silentlyA failure queue a person works every day

How does an AI scribe write notes back to the EHR?

Through one of three routes: a FHIR DocumentReference create (US Core’s clinical-note write pattern), an HL7 v2 MDM^T02 document message through the practice’s interface engine, or the EHR vendor’s own API, such as OpenEMR’s SOAP-note endpoint. The route depends on whether the EHR will hold an unsigned draft. Then come the engineering parts that decide safety: matching the right patient and encounter, a stable note identifier so retries never duplicate, a defined path for amendments, and a failure queue someone actually works.

Ambient scribe note write-back

The transcript is solved. The last metre into the chart is not.

Speech recognition and note drafting have become a crowded market, and most ambient scribes now produce a usable draft within minutes of a visit. Where products still lose customers is the step after: the clinician approves the note and then has to copy and paste it into the EHR, or the integration posts it to the wrong encounter, or a timeout leaves two copies in the chart and nobody notices until an audit.

This page covers that last step. It is written for engineering leads at scribe companies and for practice and group IT teams evaluating one. It sets out the write-back paths each EHR accepts as of November 2026, starting with OpenEMR and Oracle Health, the three ways to handle drafting and signing, and the reliability work (matching, idempotency, amendments, queues, audit) that decides whether the integration is safe to switch on.

It does not cover choosing a speech or language model or evaluating draft quality; that is on our generative AI in healthcare page. We build the plumbing as part of FHIR interoperability and healthcare interface projects, and we run our own ambient-notes module, so the failure modes below are ones we design for.

Write-back paths by EHR, November 2026

Every EHR offers some way in for a document, but they differ on the two things a scribe cares about most: can the note arrive as an unsigned draft, and does it attach to a specific visit? The table is our working summary; confirm each row against the vendor’s current documentation and the customer’s own configuration before you build.

EHRWrite-back pathDraft or final?What to watch
OpenEMR (7.x, 8.x)Standard REST API: POST /api/patient/:pid/encounter/:eid/soap_note for a structured SOAP form, or POST /api/patient/:pid/document to file a document in a chart category. FHIR DocumentReference is read-only apart from CCD generation.No draft state on the SOAP form; approve in your app first, then lock with OpenEMR’s encounter e-signature if the practice uses it.The document upload answers true, not an id, so keep your own record of what was sent. Client-credentials tokens last 60 seconds.
Oracle Health MillenniumFHIR R4 POST /DocumentReference, provisioned by each health system; HL7 v2 MDM through the hospital’s interface team.FHIR create accepts docStatus final only under provider access (final or amended under system access).Sign before you post. context.period.end is required; type is LOINC or code set 72, not both; keep the ETag for later updates.
EpicFHIR DocumentReference create for clinical notes; HL7 v2 incoming MDM for transcription-style documents.Reported to accept preliminary notes that clinicians then sign in Epic.Plain-text content and an encounter that can hold a note; see our sister team’s Epic guide.
athenaOneathenaOne’s own APIs (clinical document upload, encounter section endpoints) via its Marketplace; FHIR R4 is used for reading documents.Depends on the endpoint and practice settings.Each practice enables the app; a department id is needed when posting documents.
Any EHR with an interface engineHL7 v2 MDM^T02 (original document with content) into the engine, which routes it to the EHR’s transcription inbound.Carried in TXA-17: IP, PA, AU or LA, if the receiver honours it.The oldest and most widely supported route. Corrections need T08, T10 or T11, not a second T02.
Your own FHIR server (HAPI, Medplum, Aidbox)Full DocumentReference create, update and conditional create.Any docStatus you allow.Useful as a staging store when the EHR itself only takes final notes.

OpenEMR and Oracle rows from vendor documentation read on 13 November 2026. Epic and athenaOne rows are from secondary reports and our own notes; xcodefixglobal.com covers Epic build work in depth.

FHIR DocumentReference write-back, done carefully

US Core 9.0.0 added a page on writing clinical notes. It is marked informative, so it creates no conformance obligations yet, but it is the clearest statement of what a well-behaved server and client do: the client posts a DocumentReference with status, type (LOINC), category clinical-note, subject, content and content type; the server accepts plain text and PDF up to at least 5 MiB, and supports conditional create so a retry cannot create a second note. Notably, it lists stateful draft workflows, naming ambient scribing, as out of scope. Drafts are left to each vendor.

An illustrative request for a progress note, against a server that accepts preliminary notes:

POST [base]/DocumentReference
Content-Type: application/fhir+json
If-None-Exist: identifier=https://scribe.example.com/note-id|7f3a9c-v1

{
  "resourceType": "DocumentReference",
  "identifier": [{ "system": "https://scribe.example.com/note-id", "value": "7f3a9c-v1" }],
  "status": "current",
  "docStatus": "preliminary",
  "type": { "coding": [{ "system": "http://loinc.org", "code": "11506-3",
                         "display": "Progress note" }] },
  "category": [{ "coding": [{
      "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
      "code": "clinical-note" }] }],
  "subject": { "reference": "Patient/8812" },
  "date": "2026-11-13T10:15:02-05:00",
  "author": [{ "reference": "Practitioner/1043" }],
  "content": [{ "attachment": {
      "contentType": "text/plain; charset=utf-8",
      "data": "U1VCSkVDVElWRTogVGhyZWUgZGF5cyBvZiBkcnkgY291Z2guLi4=" } }],
  "context": {
    "encounter": [{ "reference": "Encounter/55881" }],
    "period": { "start": "2026-11-13T09:45:00-05:00", "end": "2026-11-13T10:05:00-05:00" }
  }
}
  • The identifier is yours. One value per note version (7f3a9c-v1), generated when the clinician approves, never when the request is sent. A retry reuses it; the server finds the existing note and does not create another.
  • Plain text first. It is the format every server in the table accepts. Send HTML or RTF only where the EHR renders it and the customer wants formatting.
  • Composition is the wrong tool here. Composition and document Bundles suit exchanging signed summaries between organisations (the International Patient Summary, India’s ABDM records). EHRs rarely accept them as a way to file a visit note.
  • For Oracle Health, adapt the shape: docStatus final, context as an array with a period end, and either LOINC or a code set 72 type. Oracle documents a fixed list of body fields and ignores the rest, so do not rely on your identifier or on conditional create to stop duplicates there. Store the returned Location and ETag against your note id, and search before any retry.

HL7 MDM^T02: the route that works almost everywhere

Transcription companies have filed notes over HL7 v2 for decades, so nearly every EHR and interface engine already has an MDM inbound. For a scribe that sells into practices with an engine, it is often the fastest route to production. A minimal illustrative message:

MSH|^~\&|SCRIBEAPP|CLINIC01|EHR|CLINIC01|20261113101502||MDM^T02^MDM_T02|SCR-7f3a9c-1|P|2.5.1
EVN|T02|20261113101502
PID|1||100234^^^CLINIC01^MR||SHARMA^ASHA||19800412|F
PV1|1|O|MAIN^^^CLINIC01||||D1043^REDDY^VIKRAM||||||||||||V558812^^^CLINIC01^VN
TXA|1|PN|TX|20261113094500|D1043^REDDY^VIKRAM|20261113101500||||||SCR-7f3a9c^SCRIBEAPP|||||AU||AV
OBX|1|TX|11506-3^Progress note^LN||SUBJECTIVE: Three days of dry cough, no fever.
OBX|2|TX|11506-3^Progress note^LN||ASSESSMENT: Likely viral upper respiratory infection.
OBX|3|TX|11506-3^Progress note^LN||PLAN: Fluids, review in five days if not improving.
  • PV1-19 carries the visit number, which is how the receiver finds the encounter. If the practice’s feeds leave it empty, matching falls back to date and provider, and that is where wrong-visit notes come from.
  • TXA-12, the unique document number, is your idempotency key on this route. Never reuse it for a different note.
  • TXA-17, document completion status, says how far the note has got: IP (in progress), PA (pre-authenticated), AU (authenticated) or LA (legally authenticated). Whether the EHR shows a PA note as “awaiting signature” is a receiver setting; test it.
  • TXA-19 availability (AV, UN, OB, CA) governs what you can do next. HL7 allows edits (T08) and cancellation (T11) only while a document is still unavailable for patient care; once it is available, a correction is a replacement (T10), and the original becomes obsolete but stays in the record.

Three ways to handle draft and signature

A note is a legal statement by the clinician who signs it. The integration has to make it impossible for an unreviewed draft to look like a signed note. There are three workable patterns:

  1. Sign in the scribe, post final. The clinician reviews and approves in your app; only then does anything reach the EHR, as a final document. This is the only pattern Oracle Health’s FHIR create supports, and the simplest to audit. The cost: the clinician signs in two places if the EHR also wants its own sign-off.
  2. Post preliminary, sign in the EHR. The draft lands as preliminary (FHIR) or pre-authenticated (MDM) and the clinician signs it in the EHR’s inbox. Better for clinicians who live in the EHR, but you now depend on the EHR showing draft status clearly, and on your system hearing back when the note is signed or edited.
  3. Stage outside the EHR. Drafts sit in a FHIR server or queue you control; the EHR receives only the approved version. Useful when the EHR has no draft concept, such as OpenEMR’s SOAP form, or when several systems need the same note.

Whichever you choose, write down where the legal signature lives and show it at the top of the filed note: who approved it and when.

Patient and encounter matching

  • Start from the schedule, not the recording. Pull the day’s appointments (HL7 SIU, FHIR Appointment, or the vendor API) and have the clinician pick the visit before recording. A note that starts life attached to an appointment rarely ends up on the wrong patient.
  • Carry the EHR’s ids, not names. Keep the EHR patient id, encounter id and visit number from the moment of selection. Never match on name and date of birth at write time.
  • Encounters that do not exist yet. In many practices the encounter is created at check-in or by the clinician later. Decide whether your integration waits for it, creates it (OpenEMR allows POST /api/patient/:puuid/encounter), or files to the chart without one.
  • Conflicts go to a person. Two open encounters for the same patient and day, a merged patient record, or a visit cancelled after recording: hold the note and ask, never guess.

Duplicates, retries and the timeout problem

Most duplicate notes come from retries after a timeout. The EHR stored the note, the response never arrived, and the integration sent it again. Defences, in order of strength: conditional create on your note identifier (FHIR), a unique TXA-12 the receiver de-duplicates on (MDM), and for APIs with neither, a lookup before any retry. OpenEMR’s document upload returns no id, so “search before retry” is the only safe rule there. Treat a timeout as unknown, not failed, and never auto-retry an unknown write more than once without checking.

Amendments after signing

Once a note is signed and visible to other clinicians, it is not edited in place. In FHIR, post a new DocumentReference that points to the original with relatesTo code replaces (or appends for an addendum), and mark the original superseded; Oracle accepts docStatus amended on update with the ETag in If-Match. In HL7, send T06 for an addendum or T10 for a replacement, each with its own TXA-12 and the original in TXA-13. A note filed to the wrong patient is different again: mark it entered-in-error (FHIR) or follow the receiver’s cancellation route, then file the correct note. Your app should keep the full chain, not only the latest version.

Failure queues and audit

Give every note a state and make every transition an audit event. A simple state machine we use as a starting point:

StateMeaningWho acts
draftedTranscript and draft exist; nothing is in the EHRClinician reviews
approvedClinician approved this exact text; note id assignedIntegration sends
sendingRequest in flightIntegration waits
filedEHR confirmed storage; EHR id or ETag recordedNobody
unknownTimeout or lost responseIntegration checks before any retry
retryingEHR unreachable or busy; backoff in progressIntegration, with a cap
rejectedEHR refused: unknown patient, closed encounter, bad typeA named person, the same day

A rejected note never retries by itself, because the same request will be refused again. It goes to a queue with the EHR’s error in plain words, an alert to whoever owns the queue, and a download so the clinician can still file it by hand. The audit log records who recorded, who viewed the transcript, who approved, what was sent, what the EHR answered and every retry. Keep it append-only.

PHI and BAA: the engineering scope

  • Audio is the most sensitive artefact. Decide its retention before launch; deleting it once the transcript exists is the safest default. Record patient consent before recording starts, since consent rules for recording vary by state and country.
  • Every hop is a vendor. Speech service, any language model, cloud host, logging and error tracking each touch PHI and each needs a business associate agreement in the US. Keep a diagram of the chain and keep PHI out of tools that are not covered.
  • Least privilege at the EHR. Ask only for the write scopes the route needs, such as user/DocumentReference.c?category=clinical-note or OpenEMR’s document and SOAP-note scopes, and keep read scopes to the schedule and demographics needed for matching.
  • Compliance is a separate workstream. We design and build the controls; for HIPAA programmes, risk assessments and audits, see SemperWise compliance services.

What a first EHR integration takes

Illustrative effort for a scribe company’s first write-back to one EHR on one route, in engineer-days. It excludes the EHR vendor’s and the customer’s own approval time, which often sets the calendar.

WorkWhat it coversTypical effort
Route decisionCustomer’s EHR version, settings and engine; draft and signature pattern agreed with a clinical lead3–5 engineer-days
MatchingSchedule feed or launch context, id carry-through, conflict rules4–8 engineer-days
Write-back adapterFHIR, MDM or vendor API client, idempotency, error mapping6–12 engineer-days
Amendments and signingAddendum, replacement and entered-in-error flows; status sync if signing happens in the EHR4–8 engineer-days
Queue, alerts and auditState machine, rejected-note queue, alerts, append-only audit3–6 engineer-days
Testing and go-liveVendor sandbox, customer test environment, pilot clinicians, cutover5–10 engineer-days

Total: roughly 25–49 engineer-days. A second EHR on the same pipeline is usually 10–20 engineer-days, because matching, queues and audit are reused.

Packages

Note write-back packages

Effort in engineer-days. We confirm a fixed price per phase once we have seen the target EHR, its version and the customer’s interface set-up.

Write-back design review

The problem

You have a scribe and a first customer, but no agreed route into their EHR, and the vendor documentation leaves the draft question open.

How we do it

We review the customer’s EHR, version and engine, pick the route (FHIR, MDM or vendor API), choose the draft and signature pattern with your clinical lead, and write the matching, idempotency and amendment rules down. Typically 3–5 engineer-days.

What you get

  • Route decision with reasons
  • Draft and signature pattern
  • Matching and duplicate rules
  • Test plan for the customer
How it runs

How a write-back project runs

For a first EHR on one route. Approval steps on the EHR vendor’s or customer’s side can add weeks we do not control; we plan around them.

Week 1

Route and pattern

Customer’s EHR, version and engine confirmed; route chosen; draft and signature pattern agreed with your clinical lead.

Weeks 2–4

Build

Matching, adapter, idempotency, amendment flows, failure queue and audit, tested against the vendor sandbox.

Weeks 4–6

Customer testing

End-to-end runs in the customer’s test environment with their interface team, including forced failures and corrections.

Weeks 6–8

Pilot and handover

A small group of clinicians live, daily review of the queue, then wider roll-out, runbook and handover.

Senior engineers firstYour first call is with someone who will do the work, not a sales script.
You own everythingCode, configuration, reports and documentation stay in your accounts and are handed over.
We run our own products15 live platforms we build and operate, so we feel production pain too.
Honest about fitIf a cheaper route or another provider suits you better, we will say so.
FAQ

AI scribe EHR integration: common questions

By one of three routes: a FHIR DocumentReference create using the clinical-note category, an HL7 v2 MDM^T02 document message through the practice’s interface engine, or the EHR vendor’s own API. Which one fits depends on the EHR, its version, whether it can hold an unsigned draft and what the practice has already enabled.

It means posting the approved note to the EHR as a FHIR DocumentReference resource: patient, encounter, author, a LOINC note type such as 11506-3 for a progress note, the clinical-note category and the text as an attachment. US Core 9.0.0 describes the pattern, including conditional create on an identifier so retries do not create duplicate notes.

Only where the EHR supports a draft state over that route. Oracle Health’s FHIR create accepts final notes only under provider access, so review must happen in the scribe first. HL7 MDM can carry a pre-authenticated status in TXA-17 if the receiver honours it. OpenEMR’s SOAP form has no draft state.

Give each approved note version a stable identifier before sending, and reuse it on any retry: conditional create with If-None-Exist in FHIR, or the same TXA-12 document number in HL7 MDM. Treat a timeout as unknown, check whether the note arrived, and only then retry.

Signed notes are not edited in place. In FHIR, post a new DocumentReference that replaces or appends to the original through relatesTo, and supersede the original. In HL7 v2, send T06 for an addendum or T10 for a replacement, each with a new document number and the original in TXA-13. Wrong-patient notes are marked entered-in-error.

Not for visit notes. OpenEMR’s FHIR DocumentReference supports reading and the $docref operation that generates a CCD. Notes are written through its standard REST API, either as a SOAP-note form on an encounter or as a document filed into a chart category, using scopes for those endpoints.

In the US, a scribe that receives, stores or processes PHI for a practice is a business associate and needs a business associate agreement, as does each of its subcontractors that touches PHI, such as speech, model and hosting providers. We handle the engineering controls; compliance programmes are covered by SemperWise.

For a first EHR on one route, our typical range is 25 to 49 engineer-days, spread over six to eight weeks because customer and vendor approvals take time. A second EHR on the same pipeline is usually 10 to 20 engineer-days.

Last updated