medirecords-integration

name	medirecords-integration
description	Complete MediRecords FHIR/REST API integration guide for Dr. Sophia AI consultations. Covers two-phase workflow (FHIR Encounter creation + REST notes append), patient search, SOAP note formatting, and troubleshooting. Use when integrating MediRecords API, creating consultations, debugging FHIR/REST endpoints, or saving AI consultations to patient records.

MediRecords Integration Guide

Overview

Access the complete guide for integrating Dr. Sophia AI consultations with MediRecords EHR system using FHIR v1 and REST v1 APIs. This skill provides the two-phase workflow, API credentials, FHIR schemas, troubleshooting guide, and test scripts.

Keywords: MediRecords, FHIR API, REST API, consultation creation, SOAP notes, encounter, EHR integration, patient records, clinical documentation

Status: ✅ Fully tested and working (verified Oct 22, 2025)

When to Use This Skill

• Creating consultations in MediRecords
• Integrating AI consultation workflow
• Debugging FHIR/REST API issues
• Saving SOAP notes to patient records
• Understanding two-phase consultation process
• Troubleshooting HTTP 409/500/400 errors

The Two-Phase Process

MediRecords requires TWO separate API calls to create a complete consultation:

Phase 1: FHIR API - Create Encounter

• Endpoint: POST https://api.medirecords.com/fhir/v1/Encounter
• Token: FHIR token (see references/api-credentials.md)
• Purpose: Create consultation structure
• Result: Encounter ID for Phase 2

Phase 2: REST API - Append Notes

• Endpoint: POST https://api.medirecords.com/v1/patients/{id}/consults/{encounterId}/consultnote/append
• Token: REST token (different from FHIR!)
• Purpose: Add clinical documentation (SOAP notes)
• Result: Consultation visible in MediRecords UI

Critical Requirements

✅ Must create encounter with status: "finished" (not "in-progress") ✅ Must include serviceProvider field (practice ID) ✅ Must append notes within 1 hour of encounter endTime ✅ Use FHIR token for Phase 1, REST token for Phase 2 (different tokens!)

Quick Start Workflow

Step 1: Search for Patient

const searchResponse = await fetch(
  'https://api.medirecords.com/fhir/v1/Patient?email=[e-mail]',
  {
    headers: {
      'Authorization': `Bearer ${FHIR_TOKEN}`,
      'Content-Type': 'application/fhir+json'
    }
  }
);
const patientData = await searchResponse.json();
const patientId = patientData.entry[0].resource.id;

Step 2: Create Finished Encounter (Phase 1)

const encounterResponse = await fetch(
  'https://api.medirecords.com/fhir/v1/Encounter',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${FHIR_TOKEN}`,
      'Content-Type': 'application/fhir+json'
    },
    body: JSON.stringify({
      resourceType: 'Encounter',
      status: 'finished',  // ✅ MUST be "finished"
      class: {
        system: 'http://terminology.hl7.org/CodeSystem/v3-ActCode',
        code: 'AMB',
        display: 'ambulatory'
      },
      subject: { reference: `Patient/${patientId}` },
      participant: [{
        individual: { reference: `Practitioner/${DR_SOPHIA_ID}` }
      }],
      serviceProvider: {  // ✅ REQUIRED!
        reference: `Organization/${PRACTICE_ID}`
      },
      period: {
        start: new Date(Date.now() - 30*60000).toISOString(),
        end: new Date().toISOString()
      }
    })
  }
);
const encounter = await encounterResponse.json();
const encounterId = encounter.id;

Step 3: Append SOAP Notes (Phase 2)

const soapNotes = `
<div id="stamp">
  <div><strong>${new Date().toLocaleString('en-AU')}</strong></div>
  <div><strong>Dr. Sophia AI - Consultation Notes</strong></div>
</div>
<p><strong>Chief Complaint:</strong> Headaches for 3 months</p>
<p><strong>Subjective:</strong> Patient reports...</p>
<p><strong>Objective:</strong> BP 145/92...</p>
<p><strong>Assessment:</strong> Uncontrolled hypertension</p>
<p><strong>Plan:</strong> Adjust medication...</p>
`;

const noteResponse = await fetch(
  `https://api.medirecords.com/v1/patients/${patientId}/consults/${encounterId}/consultnote/append`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${REST_TOKEN}`,  // ✅ Different token!
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ consultNote: soapNotes })
  }
);

What Works vs What Doesn't

Feature	Status	Details
Create finished consultation	✅ Works	Use FHIR API with status: "finished"
Append notes (unlimited)	✅ Works	Use REST API within 1 hour
HTML formatting in notes	✅ Works	Supports p, strong, div, ul, li, br, table
Multiple appends	✅ Works	Can append multiple times within 1 hour
Create "in-progress" consult	❌ Blocked	API returns HTTP 409 error
Update consult status	❌ No endpoint	Cannot change status after creation
Update/replace notes	❌ No endpoint	Can only append, not edit

Detailed Documentation

For complete API credentials, FHIR schemas, and troubleshooting guide, see:

• API Credentials: references/api-credentials.md
• FHIR Schemas: references/fhir-schemas.md
• Troubleshooting: references/troubleshooting-guide.md

Testing

Run integration test script:

cd .claude/skills/medirecords-integration
./scripts/test-consultation.sh [e-mail]

Expected output:

✅ Encounter created: [encounter-id]
✅ Notes appended: [note-id]
✅ Consultation visible in MediRecords UI

Integration with Dr. Sophia AI

Add to backend consultation handler (/backend/backend-proxy-enhanced-current.js):

// After consultation completes and SOAP notes extracted
if (req.body.patientIdentifier && shouldSaveToMedirecords(aiResponse)) {
  try {
    const consultationData = {
      chiefComplaint: extractedData.chiefComplaint,
      subjective: extractedData.subjective,
      objective: extractedData.objective,
      assessment: extractedData.assessment,
      plan: extractedData.plan,
      prescriptions: extractedData.prescriptions
    };

    const result = await createDrSophiaConsultationWithNotes(
      req.body.patientIdentifier,
      consultationData
    );

    console.log(`✅ Consultation saved: ${result.encounterId}`);
  } catch (error) {
    console.error('❌ Failed to save consultation:', error);
    // Don't fail the response - consultation still worked
  }
}

Common Issues Quick Reference

Error	Cause	Fix
HTTP 409	Status "in-progress"	Change to "finished"
HTTP 500	Missing serviceProvider	Add practice Organization reference
HTTP 400 (notes)	>1 hour since endTime	Use recent timestamps
Notes don't appear	Wrong token for append	Use REST token (not FHIR)
HTML not rendering	Unsupported tags	Use only: p, strong, div, ul, li, br, table

Verified Test Results

Patient: Willie Prosek ([e-mail]) Last Verified: October 22, 2025 at 8:17 PM Encounters Created: 3+ consultations Notes Appended: Multiple times per consultation UI Verification: ✅ All consultations visible in MediRecords HTML Formatting: ✅ Preserved correctly Character Limit: ✅ Tested up to 1,975 characters

---

Status: Production-ready, fully tested API Version: FHIR v1 + REST v1 Test Patient: [e-mail] Last Updated: October 22, 2025