MediRecords Integration Guide

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/​[email protected]',
  {
    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

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 [email protected]

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

Verified Test Results

Patient: Willie Prosek ([email protected]) 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: [email protected] Last Updated: October 22, 2025