FHIR R4 + US Core IG

Interoperability, Solved

ChartScribe speaks FHIR R4 natively. Complete US Core IG compliance, bidirectional Bundle export/import, SMART on FHIR authentication, and validated mapping across 8 FHIR resource types.

Architecture

How ChartScribe talks FHIR

Internal notes stay in your database. On export, we convert to FHIR R4 resources, validate against US Core IG, and POST to your EHR.

ChartScribe DB

Internal note storage

Converter

ChartScribeFHIRConverter

FHIR Bundle

R4 + US Core validated

HAPI Validate

Server-side validation

EHR Endpoint

POST /Bundle

Backend

Python FastAPI

fhir.resources library for R4 models

Validation

HAPI FHIR Server

Validation + reference implementation

Auth

SMART on FHIR

OAuth2 + contextual launch scopes

Compliance

US Core IG

8 profiles, full Must Support coverage

Complete Mapping

Internal Data → FHIR R4 → US Core IG

Every ChartScribe field maps to a specific FHIR resource path with US Core conformance requirements.

ChartScribe FieldFHIR ResourceFHIR PathUS CoreExample Value
Note IDCompositionComposition.idMust Support"note-20260620-001"
PatientCompositionComposition.subject.referenceRequired"Patient/pat-123"
ClinicianCompositionComposition.author[0].referenceRequired"Practitioner/dr-456"
Encounter DateCompositionComposition.dateRequired"2026-06-20T14:30:00Z"
StatusCompositionComposition.statusRequired"final" | "preliminary" | "amended"
Encounter TypeEncounterEncounter.classRequired{ "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB" }
SubjectiveCompositionComposition.section[0].text.divMust Support"<div>Patient reports chest pain for 2 days...</div>"
Objective (Vitals)ObservationComposition.section[1].entry → ObservationRequiredBP, HR, SpO2, Temp as Observation resources
AssessmentConditionComposition.section[2].entry → ConditionMust Support"Condition/cond-789 (Hypertension)"
PlanCarePlanComposition.section[3].entry → CarePlanRequired"CarePlan/cp-001 (Start lisinopril 10mg)"
MedicationsMedicationRequestComposition.section[4].entry → MedicationRequestRequiredList of MedicationRequest references
ICD-10 CodesConditionCondition.codeRequired{ "system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "I20.9" }
SNOMED CTConditionCondition.code.coding[1]Must Support{ "system": "http://snomed.info/sct", "code": "194828000" }
Digital SignatureCompositionComposition.attesterMust Support{ "mode": "legal", "party": "Practitioner/dr-456" }
Care Portal LinkCompositionComposition.extension[0]Optional{ "url": "https://chartscribe.io/care", "valueBoolean": true }
Resource Profiles

8 FHIR Resource Profiles

Each resource follows its US Core IG profile with complete Must Support element coverage.

The main document resource that assembles all clinical note sections into a coherent clinical document.

PathTypeCard.Description
idid0..1Logical identifier for this composition (ChartScribe Note ID)
statuscode1..1preliminary | final | amended | entered-in-error
typeCodeableConcept1..1Kind of composition (LOINC 11506-3 for Progress Note)
subjectReference(Patient)1..1Who/what the composition is about
datedateTime1..1Composition editing time (Encounter date)
authorReference(Practitioner)1..*Who wrote the composition (Clinician)
titlestring1..1Human-readable name (e.g. "Progress Note")
attesterBackboneElement0..*Attests to accuracy (Digital signature)
sectionBackboneElement0..*SO(A)P sections as narrative + references
Implementation

Ready-to-Run Python Code

Complete FastAPI implementation. Copy, paste, and start converting.

python
from datetime import datetime
from typing import Dict, List, Optional
import json

# ── ChartScribe → FHIR R4 Converter ──

class ChartScribeFHIRConverter:
    """Converts ChartScribe internal clinical notes to FHIR R4 resources."""

    BASE_URL = "https://api.chartscribe.io/fhir"

    def __init__(self, organization_id: str):
        self.org_id = organization_id

    def note_to_fhir_bundle(self, note: Dict) -> Dict:
        """Convert a ChartScribe note into a FHIR Transaction Bundle."""
        patient = self._build_patient(note)
        practitioner = self._build_practitioner(note)
        encounter = self._build_encounter(note, patient)
        observations = self._build_observations(note, patient, encounter)
        conditions = self._build_conditions(note, patient, encounter)
        careplan = self._build_careplan(note, patient, conditions)
        medications = self._build_medication_requests(note, patient, practitioner)
        composition = self._build_composition(
            note, patient, practitioner, encounter,
            observations, conditions, careplan, medications
        )

        entries = [
            {"fullUrl": f"{self.BASE_URL}/Composition/{note['id']}", "resource": composition, "request": {"method": "POST", "url": "Composition"}},
            {"fullUrl": f"{self.BASE_URL}/Patient/{patient['id']}", "resource": patient, "request": {"method": "POST", "url": "Patient"}},
            {"fullUrl": f"{self.BASE_URL}/Practitioner/{practitioner['id']}", "resource": practitioner, "request": {"method": "POST", "url": "Practitioner"}},
            {"fullUrl": f"{self.BASE_URL}/Encounter/{encounter['id']}", "resource": encounter, "request": {"method": "POST", "url": "Encounter"}},
            *[{ "fullUrl": f"{self.BASE_URL}/Observation/{obs['id']}", "resource": obs, "request": {"method": "POST", "url": "Observation"} } for obs in observations],
            *[{ "fullUrl": f"{self.BASE_URL}/Condition/{cond['id']}", "resource": cond, "request": {"method": "POST", "url": "Condition"} } for cond in conditions],
            {"fullUrl": f"{self.BASE_URL}/CarePlan/{careplan['id']}", "resource": careplan, "request": {"method": "POST", "url": "CarePlan"}},
            *[{ "fullUrl": f"{self.BASE_URL}/MedicationRequest/{med['id']}", "resource": med, "request": {"method": "POST", "url": "MedicationRequest"} } for med in medications],
        ]

        return {
            "resourceType": "Bundle",
            "id": f"bundle-{note['id']}",
            "meta": { "versionId": "1", "lastUpdated": datetime.utcnow().isoformat() + "Z" },
            "type": "document",
            "total": len(entries),
            "entry": entries,
        }

    def _build_composition(self, note, patient, practitioner, encounter,
                           observations, conditions, careplan, medications) -> Dict:
        """Build the Composition resource (the clinical document)."""
        return {
            "resourceType": "Composition",
            "id": note["id"],
            "meta": {
                "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-documentreference"]
            },
            "status": "final",
            "type": {
                "coding": [{
                    "system": "http://loinc.org",
                    "code": "11488-4",
                    "display": "Consultation note"
                }],
                "text": "Consultation Note"
            },
            "subject": { "reference": f"Patient/{patient['id']}" },
            "date": note["encounter_date"],
            "author": [{ "reference": f"Practitioner/{practitioner['id']}" }],
            "title": f"Consultation Note - {note['patient_name']}",
            "attester": [{
                "mode": "legal",
                "party": { "reference": f"Practitioner/{practitioner['id']}" }
            }],
            "section": [
                {
                    "title": "Subjective",
                    "code": { "coding": [{ "system": "http://loinc.org", "code": "61150-9" }] },
                    "text": { "status": "generated", "div": f"<div>{note['subjective']}</div>" },
                },
                {
                    "title": "Objective",
                    "code": { "coding": [{ "system": "http://loinc.org", "code": "61149-1" }] },
                    "text": { "status": "generated", "div": f"<div>{note['objective']}</div>" },
                    "entry": [{ "reference": f"Observation/{obs['id']}" } for obs in observations],
                },
                {
                    "title": "Assessment",
                    "code": { "coding": [{ "system": "http://loinc.org", "code": "11496-4" }] },
                    "text": { "status": "generated", "div": f"<div>{note['assessment']}</div>" },
                    "entry": [{ "reference": f"Condition/{cond['id']}" } for cond in conditions],
                },
                {
                    "title": "Plan",
                    "code": { "coding": [{ "system": "http://loinc.org", "code": "18776-5" }] },
                    "text": { "status": "generated", "div": f"<div>{note['plan']}</div>" },
                    "entry": [
                        { "reference": f"CarePlan/{careplan['id']}" },
                        *[{ "reference": f"MedicationRequest/{med['id']}" } for med in medications],
                    ],
                },
            ],
        }

    def _build_patient(self, note: Dict) -> Dict:
        """Build US Core Patient resource."""
        return {
            "resourceType": "Patient",
            "id": note["patient_id"],
            "meta": { "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"] },
            "identifier": [{
                "system": f"https://{self.org_id}.chartscribe.io/mrn",
                "value": note["patient_id"],
            }],
            "name": [{ "use": "official", "family": note["patient_last"], "given": [note["patient_first"]] }],
            "gender": note.get("gender", "unknown"),
        }

    def _build_practitioner(self, note: Dict) -> Dict:
        """Build US Core Practitioner resource."""
        return {
            "resourceType": "Practitioner",
            "id": note["clinician_id"],
            "meta": { "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner"] },
            "identifier": note.get("clinician_identifiers", []),
            "name": [{ "use": "official", "family": note["clinician_last"], "given": [note["clinician_first"]], "prefix": ["Dr."] }],
        }

    def _build_encounter(self, note: Dict, patient: Dict) -> Dict:
        """Build US Core Encounter resource."""
        return {
            "resourceType": "Encounter",
            "id": f"enc-{note['id']}",
            "meta": { "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter"] },
            "status": "finished",
            "class": { "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": note.get("encounter_class", "AMB") },
            "type": [{ "coding": [{ "system": "http://snomed.info/sct", "code": "185349003", "display": "Encounter for check up" }] }],
            "subject": { "reference": f"Patient/{patient['id']}" },
            "period": { "start": note["encounter_date"], "end": note["encounter_end_date"] },
        }

    def _build_observations(self, note: Dict, patient: Dict, encounter: Dict) -> List[Dict]:
        """Extract vitals from objective section and build Observation resources."""
        observations = []
        vitals = self._parse_vitals(note.get("objective", ""))
        for vital in vitals:
            obs = {
                "resourceType": "Observation",
                "id": f"obs-{vital['type']}-{note['id']}",
                "meta": { "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-vital-signs"] },
                "status": "final",
                "category": [{ "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs" }] }],
                "code": { "coding": [{ "system": "http://loinc.org", "code": vital["loinc"], "display": vital["name"] }] },
                "subject": { "reference": f"Patient/{patient['id']}" },
                "encounter": { "reference": f"Encounter/{encounter['id']}" },
                "effectiveDateTime": note["encounter_date"],
                "valueQuantity": { "value": vital["value"], "unit": vital["unit"], "system": "http://unitsofmeasure.org", "code": vital["unit_code"] },
            }
            if vital["type"] == "bp":
                obs["component"] = [
                    { "code": { "coding": [{ "system": "http://loinc.org", "code": "8480-6" }] }, "valueQuantity": { "value": vital["systolic"], "unit": "mmHg" } },
                    { "code": { "coding": [{ "system": "http://loinc.org", "code": "8462-4" }] }, "valueQuantity": { "value": vital["diastolic"], "unit": "mmHg" } },
                ]
                del obs["valueQuantity"]
            observations.append(obs)
        return observations

    def _build_conditions(self, note: Dict, patient: Dict, encounter: Dict) -> List[Dict]:
        """Parse ICD-10 codes from assessment and build Condition resources."""
        conditions = []
        for i, dx in enumerate(note.get("diagnoses", [])):
            conditions.append({
                "resourceType": "Condition",
                "id": f"cond-{i}-{note['id']}",
                "meta": { "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-condition-encounter-diagnosis"] },
                "clinicalStatus": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active" }] },
                "verificationStatus": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status", "code": "confirmed" }] },
                "category": [{ "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/condition-category", "code": "encounter-diagnosis" }] }],
                "code": {
                    "coding": [
                        { "system": "http://hl7.org/fhir/sid/icd-10-cm", "code": dx["icd10"], "display": dx["description"] },
                        { "system": "http://snomed.info/sct", "code": dx.get("snomed", ""), "display": dx["description"] },
                    ],
                    "text": dx["description"],
                },
                "subject": { "reference": f"Patient/{patient['id']}" },
                "encounter": { "reference": f"Encounter/{encounter['id']}" },
            })
        return conditions

    def _build_careplan(self, note: Dict, patient: Dict, conditions: List[Dict]) -> Dict:
        """Build US Core CarePlan from the Plan section."""
        activities = []
        for i, action in enumerate(note.get("plan_actions", [])):
            activities.append({
                "reference": { "display": action },
                "detail": { "status": "scheduled", "description": action },
            })
        return {
            "resourceType": "CarePlan",
            "id": f"cp-{note['id']}",
            "meta": { "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-careplan"] },
            "status": "active",
            "intent": "plan",
            "title": f"Care Plan for {note['patient_name']}",
            "subject": { "reference": f"Patient/{patient['id']}" },
            "addresses": [{ "reference": f"Condition/{c['id']}" } for c in conditions[:2]],
            "activity": activities,
        }

    def _build_medication_requests(self, note: Dict, patient: Dict, practitioner: Dict) -> List[Dict]:
        """Build US Core MedicationRequest resources from prescriptions."""
        meds = []
        for i, med in enumerate(note.get("medications", [])):
            meds.append({
                "resourceType": "MedicationRequest",
                "id": f"med-{i}-{note['id']}",
                "meta": { "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-medicationrequest"] },
                "status": "active",
                "intent": "order",
                "medicationCodeableConcept": {
                    "coding": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": med.get("rxcui", ""), "display": med["name"] }],
                    "text": med["name"],
                },
                "subject": { "reference": f"Patient/{patient['id']}" },
                "authoredOn": note["encounter_date"],
                "requester": { "reference": f"Practitioner/{practitioner['id']}" },
                "dosageInstruction": [{ "text": med.get("sig", ""), "route": { "coding": [{ "system": "http://snomed.info/sct", "code": med.get("route_code", "") }] } }],
                "dispenseRequest": { "numberOfRepeatsAllowed": med.get("refills", 0), "quantity": { "value": med.get("qty", 30) } },
            })
        return meds

    @staticmethod
    def _parse_vitals(objective_text: str) -> List[Dict]:
        """Parse vital signs from ChartScribe objective text."""
        vitals = []
        # BP parsing: "BP: 142/88 mmHg"
        import re
        bp_match = re.search(r'BP[:\s]+(\d+)[\/](\d+)', objective_text)
        if bp_match:
            vitals.append({
                "type": "bp", "name": "Blood Pressure", "loinc": "85354-9",
                "systolic": int(bp_match.group(1)), "diastolic": int(bp_match.group(2)),
                "unit": "mmHg", "unit_code": "mm[Hg]",
            })
        # HR parsing
        hr_match = re.search(r'HR[:\s]+(\d+)', objective_text)
        if hr_match:
            vitals.append({
                "type": "hr", "name": "Heart Rate", "loinc": "8867-4",
                "value": int(hr_match.group(1)), "unit": "beats/min", "unit_code": "/min",
            })
        # SpO2 parsing
        spo2_match = re.search(r'SpO2[:\s]+(\d+)', objective_text)
        if spo2_match:
            vitals.append({
                "type": "spo2", "name": "Oxygen Saturation", "loinc": "2708-6",
                "value": int(spo2_match.group(1)), "unit": "%", "unit_code": "%",
            })
        return vitals

Auto ICD-10 → SNOMED mapping

Bidirectional import/export

US Core IG validation

SMART on FHIR OAuth2

API Reference

Endpoints to Implement

Three core endpoints for FHIR export and patient data import.

GET/fhir/Patient/{id}

Import patient demographics from EHR into ChartScribe.

{ "resourceType": "Patient", "id": "...", "name": [...], ... }
POST/fhir/Composition

Export a ChartScribe note as a FHIR Composition wrapped in a document Bundle.

{ "status": "success", "bundle": { "resourceType": "Bundle", "type": "document", ... } }
GET/fhir/Composition?patient={id}

List all notes for a given patient, returned as a search Bundle.

{ "resourceType": "Bundle", "type": "searchset", "entry": [...] }
Quality Assurance

Testing & Validation Checklist

Before going live, every Bundle must pass these four gates.

Gate 1

US Core Validator

Run the official HL7 US Core IG validator against every Composition, Patient, and Encounter resource.

Gate 2

EHR Sandboxes

Test against Epic Sandbox, Cerner Code, and EMIS Test environments for real-world compatibility.

Gate 3

$validate Operation

POST every Bundle to the target FHIR server's /Bundle/$validate endpoint and resolve all OperationOutcome issues.

Gate 4

Patient Consent

Verify the patient consent flow: check chartscribe.care sharing flags, audit GDPR Article 9 compliance, and log attestation.

Sample Output

Sample FHIR Bundle

A complete document Bundle generated from a ChartScribe consultation note. Download and validate against any FHIR R4 server.

json
{
  "resourceType": "Bundle",
  "id": "bundle-note-001",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2026-06-20T14:30:00Z"
  },
  "type": "document",
  "total": 6,
  "entry": [
    {
      "fullUrl": "https://api.chartscribe.io/fhir/Composition/note-001",
      "resource": {
        "resourceType": "Composition",
        "id": "note-001",
        "status": "final",
        "type": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "11488-4",
              "display": "Consultation note"
            }
          ]
        },
        "subject": {
          "reference": "Patient/pat-123"
        },
        "date": "2026-06-20T14:30:00Z",
        "author": [
          {
            "reference": "Practitioner/dr-456"
          }
        ],
        "title": "Consultation Note - John Doe",
        "attester": [
          {
            "mode": "legal",
            "party": {
              "reference": "Practitioner/dr-456"
            }
          }
        ],
        "section": [
          {
            "title": "Subjective",
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "61150-9"
                }
              ]
            },
            "text": {
              "status": "generated",
              "div": "<div>Patient reports chest pain for 2 days...</div>"
            }
          },
          {
            "title": "Objective",
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "61149-1"
                }
              ]
            },
            "text": {
              "status": "generated",
              "div": "<div>BP: 142/88, HR: 86, SpO2: 98%</div>"
            },
            "entry": [
              {
                "reference": "Observation/obs-bp-note-001"
              }
            ]
          },
          {
            "title": "Assessment",
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "11496-4"
                }
              ]
            },
            "text": {
              "status": "generated",
              "div": "<div>1. Unstable angina (I20.0)</div>"
            },
            "entry": [
              {
                "reference": "Condition/cond-0-note-001"
              }
            ]
          },
          {
            "title": "Plan",
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "18776-5"
                }
              ]
            },
            "text": {
              "status": "generated",
              "div": "<div>1. ECG ordered stat</div>"
            },
            "entry": [
              {
                "reference": "CarePlan/cp-note-001"
              },
              {
                "reference": "MedicationRequest/med-0-note-001"
              }
            ]
          }
        ]
      }
    },
    {
      "fullUrl": "https://api.chartscribe.io/fhir/Patient/pat-123",
      "resource": {
        "resourceType": "Patient",
        "id": "pat-123",
        "identifier": [
          {
            "system": "https://org-001.chartscribe.io/mrn",
            "value": "pat-123"
          }
        ],
        "name": [
          {
            "use": "official",
            "family": "Doe",
            "given": [
              "John"
            ]
          }
        ],
        "gender": "male"
      }
    },
    {
      "fullUrl": "https://api.chartscribe.io/fhir/Practitioner/dr-456",
      "resource": {
        "resourceType": "Practitioner",
        "id": "dr-456",
        "identifier": [
          {
            "system": "http://hl7.org/fhir/sid/us-npi",
            "value": "1234567890"
          }
        ],
        "name": [
          {
            "use": "official",
            "family": "Smith",
            "given": [
              "Jane"
            ],
            "prefix": [
              "Dr."
            ]
          }
        ]
      }
    }
  ]
}
Quality Assurance

Validation & Testing

Every Bundle passes two validation gates before reaching your EHR.

Gate 1

Pydantic Validation

Using fhir.resources library for strict R4 model conformance. Catches type mismatches, missing required fields, and invalid cardinality before serialization.

Gate 2

HAPI FHIR Server

Submit to HAPI FHIR /$validate endpoint for server-side US Core IG profile validation. Returns OperationOutcome with severity-rated issues.

Resilience

Error Handling

Graceful degradation for partial failures. If one resource fails validation, the Bundle reports specific entry errors without discarding valid resources.

Public Test Endpoints

HAPI FHIR Public Test Server

http://hapi.fhir.org/baseR4

Validation + CRUD testing

SMART Launcher (Cerner)

https://launch.smarthealthit.org

SMART app launch simulation

Ready to connect your EHR?

Our integration team will configure your FHIR endpoint, set up SMART authentication, and validate the first Bundle within 48 hours.

We use cookies to improve your experience

Necessary cookies are always active. Analytics and marketing cookies help us improve ChartScribe and show relevant content. You can manage your preferences at any time.

We use cookies to improve your experience

Necessary cookies are always active. Analytics and marketing cookies help us improve ChartScribe and show relevant content. You can manage your preferences at any time.