EHR Integration Patterns

Architecture overview

SOAPNoteAPI sits between your clinical encounter and the EHR chart. Your platform captures the encounter (transcript, audio, or shorthand), sends it to SOAPNoteAPI, receives a structured SOAP note, presents it to the provider for review, and then files the approved note into the EHR. SOAPNoteAPI handles the AI generation -- your integration handles the EHR read/write.

• Input: Clinical transcript, audio recording, or provider shorthand from the encounter.
• Processing: SOAPNoteAPI generates a structured SOAP note (subjective, objective, assessment, plan) plus optional billing codes and patient summary.
• Review: The provider reviews, edits, and approves the generated note in your UI.
• Filing: Your integration writes the approved note to the EHR chart via the EHR API (FHIR, HL7, or proprietary).

Encounter workflow mapping

A typical EHR encounter follows a predictable lifecycle. Here is how SOAPNoteAPI maps to each stage:

• 1. Encounter opened -- Provider starts a visit in the EHR. Your integration reads patient context (demographics, history, medications, allergies) from the EHR to pre-populate the SOAPNoteAPI context object.
• 2. Clinical encounter -- Provider sees the patient. Audio is recorded or the provider takes shorthand notes.
• 3. Note generation -- Your integration sends the transcript/audio to SOAPNoteAPI with the patient context. For audio, use PUT /v1/note/audio. For text, use POST /v1/note or POST /v1/stream/note.
• 4. Provider review -- Display the generated SOAP note in a review interface within your EHR integration. The provider edits, approves, or regenerates.
• 5. Filing to chart -- Write the approved note to the EHR encounter record via the EHR API.
• 6. Billing -- If include_billing_codes was requested, present suggested ICD-10 and CPT codes for the provider to confirm before submitting to the billing system.

Pre-populating context from the EHR

// Read patient data from your EHR API and pass it as context
const patient = await ehrApi.getPatient(encounterId);
const medications = await ehrApi.getMedications(patient.id);
const allergies = await ehrApi.getAllergies(patient.id);
const recentVisits = await ehrApi.getRecentVisits(patient.id, { limit: 3 });

const response = await fetch("https://api.soapnoteapi.com/v1/note", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SOAPNOTEAPI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    transcript: encounterTranscript,
    specialty: mapEhrSpecialty(provider.specialty), // Map your EHR specialty to SOAPNoteAPI
    context: {
      patient_info: {
        name: patient.name,
        age: calculateAge(patient.dateOfBirth),
        gender: patient.gender,
        medical_history: patient.problemList.join(". "),
        medications: medications.map(m => `${m.name} ${m.dosage} ${m.frequency}`),
        allergies: allergies.map(a => a.allergen),
      },
      patient_history: recentVisits.map(v =>
        `${v.date}: ${v.summary}`
      ).join("\n"),
    },
    include_billing_codes: true,
  }),
});

Mapping SOAPNoteAPI output to EHR fields

SOAPNoteAPI returns four discrete sections (subjective, objective, assessment, plan) as separate string fields. Most EHR systems have corresponding fields or sections in their encounter note templates. Map each section directly.

// Map SOAPNoteAPI response to your EHR note fields
const soapNote = await response.json();

const ehrNoteFields = {
  // Direct mapping - most EHRs have these exact sections
  subjective: soapNote.subjective,
  objective: soapNote.objective,
  assessment: soapNote.assessment,
  plan: soapNote.plan,

  // Optional fields if your EHR supports them
  billingCodes: soapNote.billing_codes ? {
    icd10: soapNote.billing_codes.icd10.map(c => c.code),
    cpt: soapNote.billing_codes.cpt.map(c => c.code),
  } : null,

  patientSummary: soapNote.patient_summary, // For patient portal
};

// Write to EHR via FHIR DocumentReference or proprietary API
await ehrApi.createEncounterNote(encounterId, ehrNoteFields);

Common EHR field mappings

• FHIR DocumentReference -- Create a DocumentReference resource with the note as content. Use section codes to map S/O/A/P to LOINC codes (e.g., 10164-2 for History of Present Illness).
• Epic -- Map to SmartPhrase or NoteWriter sections. Subjective maps to HPI and ROS, Objective to Physical Exam and Results, Assessment to Diagnoses, Plan to Orders and Instructions.
• Cerner (Oracle Health) -- Use the Clinical Documentation API. Map sections to the encounter note template fields.
• Athenahealth -- Use the Encounter API. Map to HPI, exam, assessment, and plan sections.
• Custom/proprietary EHR -- Map to your note template fields. Most EHRs with a SOAP template have direct field-to-field mapping.

Note review and approval UX

The review interface is the most critical part of your EHR integration. It determines whether providers trust and adopt the AI documentation feature. Key design principles:

• Show the note inline where providers already work. A separate window or application adds friction. Embed the review step within the existing encounter closing workflow.
• Make editing frictionless. Providers should be able to click into any section and edit directly. Pre-populate with the generated text.
• Highlight what the AI generated vs. what the provider changed. This supports audit trails and helps providers learn to trust the output over time.
• Provide a "Regenerate" option. If the note quality is poor, let the provider regenerate with a single click rather than manually rewriting.
• Add an "Approve and file" action. A single button should write the reviewed note to the EHR chart. The provider should never have to copy-paste.

Handling provider edits

After the provider edits the generated note, you need to decide how to handle the edited version:

• Store the edited version only. This is the simplest approach. The EHR gets the final provider-approved text. Do not send the edit back to SOAPNoteAPI.
• Store both versions. Keep the original AI-generated note and the provider-edited note for audit purposes. This helps you track AI accuracy over time and improve the integration.
• Do not re-generate from edits. Provider edits to a generated note should be stored locally, not sent back to SOAPNoteAPI for re-processing. Re-generating would overwrite the provider nuances.

Real-world example: Chrome Extension

SOAPNoteAPI built a Chrome Extension that integrates with EHR web applications as a reference architecture. The extension injects a sidebar into the EHR browser interface, captures the provider transcript, sends it to SOAPNoteAPI, and lets the provider review and insert the note into the EHR fields. This pattern works with any web-based EHR without requiring API access.

• Content script reads the encounter page DOM to extract patient context.
• Provider records or types the encounter in the sidebar.
• Note is generated and displayed in the sidebar for review.
• Provider clicks "Insert" to populate EHR form fields via DOM manipulation.
• No backend EHR API required -- works via browser automation.

Integration patterns by EHR type

FHIR-enabled EHRs

For EHRs that support FHIR R4, build a SMART on FHIR application. Read patient context from the FHIR Patient, Condition, MedicationRequest, and AllergyIntolerance resources. Write the approved note as a DocumentReference resource.

Web-based EHRs without APIs

For web-based EHRs without open APIs, a Chrome Extension or browser-based sidebar is the most practical approach. Use content scripts to read the encounter page and inject the reviewed note into form fields. This is how the SOAPNoteAPI Chrome Extension works with SimplePractice and similar platforms.

Desktop EHRs

For native desktop EHR applications, build a companion web application that the provider accesses in a separate browser tab or embedded browser. The companion app handles the SOAPNoteAPI integration, and the provider copies the approved note to the EHR. This is less integrated but requires no EHR modification.

HIPAA considerations

• Execute a BAA with SOAPNoteAPI before sending patient data. Contact support@soapnoteapi.com to request a BAA.
• Minimize PHI sent to SOAPNoteAPI. Send only the clinical context needed for accurate note generation.
• Do not log SOAPNoteAPI response bodies (they contain the clinical note) in your application logs.
• Notes are automatically deleted from SOAPNoteAPI after the retention period. Store the approved note in your EHR, not in SOAPNoteAPI.
• Audit trail: Log that a note was generated by SOAPNoteAPI (with the noteId) but do not log the note content itself.