FHIR and HL7 for software teams
How health systems exchange data today: HL7 v2 messages inside hospitals, FHIR APIs between apps, and the US rules that make FHIR access a requirement.
What FHIR and HL7 is
HL7 FHIR and HL7 Version 2 health data exchange standards, and the US rules that require them
HL7 International is the standards body behind the two formats most health software must speak. HL7 Version 2 is the messaging standard most hospitals still use inside their walls, for admissions, orders and results. FHIR (Fast Healthcare Interoperability Resources) is its web API standard.
FHIR models health data as resources, such as Patient, Observation, Encounter and MedicationRequest, exchanged as JSON over REST. Release 4 (version 4.0.1) is the version most regulations and products use today. Release 5 is the current published release.
FHIR is a standard, not a law. It becomes a legal duty through rules that require it. In the US, certified health IT must offer a standardized FHIR API, payers must run FHIR APIs under CMS rules, and blocking access to electronic health information is restricted. Other countries build national programmes on FHIR too.
Who it applies to
Health IT developers
EHR and health IT vendors whose products are certified under the US ONC program must offer a standardized FHIR API for patient and population services.
Payers
Payers named in the CMS interoperability rules, such as Medicare Advantage organisations and state Medicaid and CHIP programmes, must run FHIR APIs for members, providers and other payers.
Apps and data platforms
Patient apps, analytics platforms and digital health products that connect to EHRs or payers use FHIR, SMART App Launch and, for large exports, FHIR Bulk Data.
Outside the US, FHIR is often required by national programmes rather than one federal rule, so check the local health data authority. Using FHIR does not make data exchange lawful on its own: privacy rules such as HIPAA and the GDPR still decide who may see what.
Key requirements, and what they mean for the build
Each row links the official text. Read the source for the exact wording before you rely on it.
Resources and REST API
FHIR defines resources, data types, search parameters and RESTful operations, plus profiles and extensions to fit local needs.
Model your internal data so it maps cleanly to the resources you exchange, and keep the mapping in one tested layer, not spread across features.
Source: HL7 FHIR R4 (v4.0.1)
US Core profiles
US Core sets the minimum profiles, must-support elements and search rules for US FHIR servers, based on the USCDI data set.
Validate every resource you send or receive against the US Core profiles, and handle missing must-support data without failing.
Source: HL7 US Core Implementation Guide
Authorisation for apps
SMART App Launch uses OAuth 2.0 and OpenID Connect to let apps launch from an EHR or stand alone, with scopes that limit what data they may read or write.
Request the narrowest scopes the feature needs, refresh tokens safely, and support both EHR launch and standalone launch.
Source: HL7 SMART App Launch
Population-level exports
FHIR Bulk Data defines asynchronous export of data for a group of patients, delivered as NDJSON files.
Treat exports as long-running jobs with retries, deduplicate on load, and track which export each record came from.
Source: HL7 FHIR Bulk Data Access
HL7 v2 messages
HL7 v2 messages, such as ADT for admissions and ORU for results, carry most real-time data inside hospitals, usually over MLLP.
An interface engine or adapter that acknowledges, queues and replays messages, and handles each site's local variations.
Source: HL7 Version 2 product brief
Certified standardized API
Certified health IT must respond to single-patient and multi-patient requests using the adopted FHIR standards, including US Core and SMART, with all must-support data elements.
If you sell certified health IT, build the API to the adopted versions and test against the official test tools before certification.
Source: 45 CFR 170.315: certification criteria, (g)(10) standardized API (eCFR)
Information blocking
Health care providers, developers of certified health IT, and health information networks and exchanges must not interfere with access, exchange or use of electronic health information, except under listed exceptions such as privacy, security or infeasibility.
Document why any data request is refused or delayed, and map each refusal to an exception. Do not add fees or delays to API access that the rules do not allow.
Payer APIs and prior authorization
Impacted payers must build FHIR-based APIs, including Patient Access, Provider Access, Payer-to-Payer and Prior Authorization APIs. Some provisions apply from 1 January 2026, and most API requirements from 1 January 2027.
Plan the payer APIs as products with their own SLAs, member consent flows and usage reporting, not as one-off integrations.
Source: CMS Interoperability and Prior Authorization Final Rule (CMS-0057-F)
Engineering controls for FHIR and HL7
How the rules change the way the software is designed.
- 01
Canonical data model
One internal model with tested mappings to FHIR resources and HL7 v2 segments, so a new integration is a new mapping, not a new data model.
- 02
Profile validation
Every inbound and outbound resource is validated against the profiles you claim, with errors reported, not silently dropped.
- 03
Patient matching
Clear rules for matching identities across systems, with uncertain matches sent to a person instead of merged automatically.
- 04
Consent and scopes
SMART scopes and consent records decide what each app and user may see, enforced on the server for every request.
- 05
Message reliability
Acknowledgements, retries, dead-letter queues and replay for HL7 v2 feeds and webhooks.
- 06
Terminology
Code systems such as LOINC, SNOMED CT and ICD-10 handled through a terminology service, with local codes mapped and versioned.
- 07
Audit of data access
Who called which endpoint for which patient and when, kept for privacy reviews and information blocking questions.
- 08
Conformance testing
Automated tests against the official implementation guide test kits and against each partner's sandbox.
Key dates
- 1 January 2026First provisions of the CMS Interoperability and Prior Authorization rule apply to impacted payers.
- 1 January 2027Most of that rule's API requirements apply.
Implementation guides are versioned and move faster than regulations. Check which version of US Core, SMART and Bulk Data your rule or partner requires before building.
Checked against the official sources on 2026-10-25.
8 OceanLab product builds cite FHIR and HL7
Counted from our published case studies: a build counts when FHIR and HL7 is in the list of rules it was built for.
Headgate - FHIR Interoperability API Platform for Claims, Clinical Data and Prior Authorization
Designed and built a clickable console for the FHIR APIs a US regional health plan must run under federal interoperability rules: API health across Patient Access, Provider Directory, Formulary, Provider Access, Payer-to-Payer and Prior Authorization, a security review queue for third-party apps, and one clock for every prior authorization request, however it arrived.
Sutura - HIPAA-Compliant Patient Data Hub over HL7 and FHIR
Designed and built a clickable patient data hub for a US health system running Epic, Oracle Health, athenahealth and eClinicalWorks: a live monitor for every HL7 v2, FHIR and HIE feed, one matched enterprise patient with a provenance-tagged record, and a duplicates queue where a person decides every uncertain match.
Loupe - Ophthalmology EHR with Per-Eye Charting and Laterality-Aware Coding
Designed and built a clickable ophthalmology EHR for a US eye care group with seven clinics: a clinician's day at a glance, a live patient flow board with dilation timers, patient search with break-the-glass access, a chart summary with right-eye and left-eye findings side by side, and a structured exam workspace per eye.
Tavor - Member Portal for an Israeli Health Fund with Family Proxy Access
Designed and built a clickable member portal for an Israeli health fund: one login for a member and the children and parents they look after, referrals and tofes 17 commitments with an honest status, and test results with plain-language explanations, held results and teen confidentiality built in.
Qistas - Health Claims Adjudication with an Explanation on Every Line
Designed and built a clickable claims adjudication platform for a Saudi cooperative health insurer: claims arrive through NPHIES, from member reimbursements or on paper, a rules engine decides each line with a trace and a provider explanation in Arabic and English, and only uncertain lines reach a medical reviewer.
Berth - Live Bed Board and Patient Flow for a Two-Site NHS Hospital Trust
Designed and built a clickable bed and capacity management system for a two-site NHS acute trust: a command centre with the day's bed balance, a live bed board for every ward and bay, a bed request queue that suggests safe beds with reasons, and a cleaning board that turns dirty beds around for the patients waiting on them.
Check your product
Other frameworks and industries
Build with FHIR and HL7 in mind from day one
Project build
We design and build the system as one project. It starts with a clickable prototype your team tries before any production code is written. Pay per milestone (outcome-based) or hourly at $30-50/hr, depending on role and seniority.
Embedded engineers
Our engineers join your team on a flexible monthly retainer. Part-time is fine and it runs month to month, with hours that overlap the US, UK and Europe, the Middle East, and Australia and Asia. Outcome-based or $30-50/hr.
FHIR and HL7 questions
Should we build on FHIR or HL7 v2?
Usually both. Hospitals still send most real-time events as HL7 v2, while apps, payers and regulators use FHIR. A good integration layer speaks both and maps them to one internal model.
Which FHIR version should we use?
R4 for most production work today, because US Core, ONC certification and most national programmes are built on it. R5 is published, but check what your partners and regulators require before moving.
Does using FHIR make us HIPAA compliant?
No. FHIR is how data moves. HIPAA, the GDPR and local laws decide who may receive it and how it is protected. You need both.
What is SMART on FHIR?
It is the HL7 standard for authorising apps against a FHIR server, based on OAuth 2.0. It lets an app launch inside an EHR or on its own, with scopes that limit what it can see.
How does OceanLab approach FHIR and HL7 on a build?
We design the internal data model and the mapping layer first, validate against the profiles you need, and test against partner sandboxes early. The builds below list FHIR or HL7 in the rules they were built for.
Official sources
- HL7 FHIR specification (current release)
- HL7 FHIR R4 (v4.0.1)
- HL7 US Core Implementation Guide
- HL7 SMART App Launch
- HL7 FHIR Bulk Data Access
- HL7 Version 2 product brief
- 45 CFR 170.315: certification criteria, (g)(10) standardized API (eCFR)
- 45 CFR Part 171: information blocking (eCFR)
- CMS Interoperability and Prior Authorization Final Rule (CMS-0057-F)
