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.
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
Python FastAPI
fhir.resources library for R4 models
HAPI FHIR Server
Validation + reference implementation
SMART on FHIR
OAuth2 + contextual launch scopes
US Core IG
8 profiles, full Must Support coverage
Every ChartScribe field maps to a specific FHIR resource path with US Core conformance requirements.
| ChartScribe Field | FHIR Resource | FHIR Path | US Core | Example Value |
|---|---|---|---|---|
| Note ID | Composition | Composition.id | Must Support | "note-20260620-001" |
| Patient | Composition | Composition.subject.reference | Required | "Patient/pat-123" |
| Clinician | Composition | Composition.author[0].reference | Required | "Practitioner/dr-456" |
| Encounter Date | Composition | Composition.date | Required | "2026-06-20T14:30:00Z" |
| Status | Composition | Composition.status | Required | "final" | "preliminary" | "amended" |
| Encounter Type | Encounter | Encounter.class | Required | { "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB" } |
| Subjective | Composition | Composition.section[0].text.div | Must Support | "<div>Patient reports chest pain for 2 days...</div>" |
| Objective (Vitals) | Observation | Composition.section[1].entry → Observation | Required | BP, HR, SpO2, Temp as Observation resources |
| Assessment | Condition | Composition.section[2].entry → Condition | Must Support | "Condition/cond-789 (Hypertension)" |
| Plan | CarePlan | Composition.section[3].entry → CarePlan | Required | "CarePlan/cp-001 (Start lisinopril 10mg)" |
| Medications | MedicationRequest | Composition.section[4].entry → MedicationRequest | Required | List of MedicationRequest references |
| ICD-10 Codes | Condition | Condition.code | Required | { "system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "I20.9" } |
| SNOMED CT | Condition | Condition.code.coding[1] | Must Support | { "system": "http://snomed.info/sct", "code": "194828000" } |
| Digital Signature | Composition | Composition.attester | Must Support | { "mode": "legal", "party": "Practitioner/dr-456" } |
| Care Portal Link | Composition | Composition.extension[0] | Optional | { "url": "https://chartscribe.io/care", "valueBoolean": true } |
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.
| Path | Type | Card. | Description |
|---|---|---|---|
| id | id | 0..1 | Logical identifier for this composition (ChartScribe Note ID) |
| status | code | 1..1 | preliminary | final | amended | entered-in-error |
| type | CodeableConcept | 1..1 | Kind of composition (LOINC 11506-3 for Progress Note) |
| subject | Reference(Patient) | 1..1 | Who/what the composition is about |
| date | dateTime | 1..1 | Composition editing time (Encounter date) |
| author | Reference(Practitioner) | 1..* | Who wrote the composition (Clinician) |
| title | string | 1..1 | Human-readable name (e.g. "Progress Note") |
| attester | BackboneElement | 0..* | Attests to accuracy (Digital signature) |
| section | BackboneElement | 0..* | SO(A)P sections as narrative + references |
Complete FastAPI implementation. Copy, paste, and start converting.
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 vitalsAuto ICD-10 → SNOMED mapping
Bidirectional import/export
US Core IG validation
SMART on FHIR OAuth2
Three core endpoints for FHIR export and patient data import.
/fhir/Patient/{id}Import patient demographics from EHR into ChartScribe.
{ "resourceType": "Patient", "id": "...", "name": [...], ... }/fhir/CompositionExport a ChartScribe note as a FHIR Composition wrapped in a document Bundle.
{ "status": "success", "bundle": { "resourceType": "Bundle", "type": "document", ... } }/fhir/Composition?patient={id}List all notes for a given patient, returned as a search Bundle.
{ "resourceType": "Bundle", "type": "searchset", "entry": [...] }Before going live, every Bundle must pass these four gates.
Run the official HL7 US Core IG validator against every Composition, Patient, and Encounter resource.
Test against Epic Sandbox, Cerner Code, and EMIS Test environments for real-world compatibility.
POST every Bundle to the target FHIR server's /Bundle/$validate endpoint and resolve all OperationOutcome issues.
Verify the patient consent flow: check chartscribe.care sharing flags, audit GDPR Article 9 compliance, and log attestation.
A complete document Bundle generated from a ChartScribe consultation note. Download and validate against any FHIR R4 server.
{
"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."
]
}
]
}
}
]
}Every Bundle passes two validation gates before reaching your EHR.
Using fhir.resources library for strict R4 model conformance. Catches type mismatches, missing required fields, and invalid cardinality before serialization.
Submit to HAPI FHIR /$validate endpoint for server-side US Core IG profile validation. Returns OperationOutcome with severity-rated issues.
Graceful degradation for partial failures. If one resource fails validation, the Bundle reports specific entry errors without discarding valid resources.
HAPI FHIR Public Test Server
http://hapi.fhir.org/baseR4
Validation + CRUD testing
SMART Launcher (Cerner)
https://launch.smarthealthit.org
SMART app launch simulation
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.