Agent skill

medirecords-integration

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.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/medirecords-integration-adaptationio-skrillz-2

SKILL.md

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 endTimeUse FHIR token for Phase 1, REST token for Phase 2 (different tokens!)

Quick Start Workflow

Step 1: Search for Patient

javascript
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)

javascript
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)

javascript
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:

bash
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):

javascript
// 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 ([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

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results