MediRecords Integration Guide Skill

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=patient@example.com',
  {
    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 willie@adaptation.io

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 (willie@adaptation.io) 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: willie@adaptation.io Last Updated: October 22, 2025

Agent Skills: MediRecords Integration Guide

Install this agent skill to your local

Skill Files