If you're integrating with a US healthcare organisation in 2026, FHIR is where you start. HL7 v2 is still everywhere in the walls of the EMR, but the interfaces the outside world touches — the patient-access API, the provider-directory API, the payer-mandated APIs — are all FHIR. The regulators have decided.
What FHIR actually is
FHIR (Fast Healthcare Interoperability Resources) is a family of standards from HL7 International. Version 4.0.1 (R4) is the current implementable version in production; R5 is finalising. FHIR is RESTful, JSON-first, HTTPS-based, and designed by people who had actually seen a modern web API.
The core primitive is a Resource — a JSON object representing a clinical or administrative entity (Patient, Encounter, Observation, MedicationRequest, Practitioner, Organization, Claim, ExplanationOfBenefit, etc.). There are around 150 resource types in R4.
The regulatory push
**CMS Interoperability and Patient Access Rule** — mandates FHIR-based patient-access APIs for most US payers. **21st Century Cures Act — Information Blocking Rule** — providers must share clinical data with patients on request. **CMS Prior Authorization Rule** — coming, mandates FHIR-based prior-auth APIs.
The net effect: every US payer and most large providers now expose FHIR APIs to at least some population.
The FHIR endpoints you'll actually build against
**Patient / Encounter / Observation** — the clinical trio. Patient identity, care events, and clinical readings (labs, vitals). About 60% of the reads on any real FHIR API.
**MedicationRequest / MedicationStatement / AllergyIntolerance / Condition** — the med / problem list trio. Care history.
**DocumentReference / DiagnosticReport / Binary** — the unstructured doc endpoints. Where PDFs, lab reports and imaging live.
**Coverage / Claim / ExplanationOfBenefit** — the money side. Insurance coverage, claims submitted, EOBs returned.
**Practitioner / Organization / Location** — the directory endpoints.
Auth: SMART on FHIR
FHIR itself doesn't specify auth. The industry standard is SMART on FHIR — OAuth 2.0 + OpenID Connect, with FHIR-specific scopes (`patient/*.read`, `user/Observation.write`, etc.). If you're not building against SMART, you're not building against FHIR seriously.
SMART also defines app-launch flows — how a third-party app launches inside the EMR with a patient context. This is how modern EMR-embedded apps work.
The pain points to expect
**Vendor drift.** Epic's FHIR is not Cerner's is not athenaHealth's. All conform to R4, all have quirks. Plan for a per-vendor test suite.
**US Core profiles.** The US Core Implementation Guide constrains which fields are mandatory in the US context. Most vendors implement US Core; make sure your app requires only US Core mandatories, otherwise you'll get null pointer exceptions in the wild.
**Bulk data vs single-patient.** Bulk FHIR ($export) is a completely different beast from patient-scoped reads. Different rate limits, different auth scopes, different pagination. Plan accordingly.
**Rate limits.** Vendor rate limits are aggressive and undocumented. Expect 429s. Design retries, jitter, and back-off from day one.
The FHIR-adjacent tooling to know
**HAPI FHIR** — Java reference implementation. The default self-hosted FHIR server.
**Medplum, Aidbox, Firely Server** — commercial FHIR servers. Modern DX, hosted or self-hosted.
**Inferno** — official FHIR conformance test suite. Every serious FHIR integration is validated against Inferno.
**Synthea** — synthetic patient data generator. Test your FHIR app against realistic data without HIPAA risk.
How Origami approaches FHIR builds
We start with the vendor stack the client actually connects to (Epic, Cerner/Oracle Health, athenaHealth, Meditech, Veradigm) and build a small conformance harness before writing a single line of business logic. Once we know exactly what the vendor's FHIR returns, we build the app on top with confidence.
Every FHIR integration we've shipped has taken 30-40% less time in the second month than the first — because the first month is 90% about understanding vendor quirks. Once the conformance harness is in place, everything else moves.