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.

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

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

Repository: fernandezbaptiste/Skrillz
Path: skill-builder-package/examples/medirecords-integration/SKILL.md
Commit: 93ed392

Last updated: 1 day ago
First committed: 10 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.