Healthcare

HL7 FHIR Integration: A Practical Developer Guide 2026 

Kishan Kataria

Published: Nov 16, 2026 12 min read
HL7 FHIR integration: a developer's guide for 2026

FHIR integration is now the standard way for healthcare apps to exchange data with EHRs, labs, payers and national health systems. If your app needs to read a patient’s history from Epic, send results back to a clinic’s EHR, or share records through a national network, you will almost certainly do it through HL7 FHIR. 

This developer’s guide explains FHIR integration step by step the core concepts, common integration patterns, SMART on FHIR authentication, working code examples, validation, security and go-live. It’s the same process our healthcare app development team follows at BriskCovey. 

Key Takeaways 

  • FHIR is a REST API for health data. Resources like Patient, Observation and Encounter are read and written as JSON over HTTPS. 
  • Target FHIR R4 first. It is the most widely deployed version and the one most EHRs and regulations expect today. 
  • Implementation guides matter as much as the base spec. US Core, ABDM profiles and EHR-specific rules decide what “valid” data looks like. 
  • SMART on FHIR handles authorization. It builds on OAuth 2.0 for user-facing apps and backend services. 
  • Plan realistic timelines. A focused FHIR integration with one EHR typically takes 6–12 weeks, mostly because of EHR app review and testing. 

What Is HL7 FHIR? 

HL7 FHIR (Fast Healthcare Interoperability Resources) is a standard from HL7 International for exchanging healthcare data. It models clinical and administrative data as small, reusable resources and exposes them through a RESTful API using JSON or XML over HTTPS. For developers, FHIR integration feels like working with any modern web API, with healthcare-specific rules on top. 

Version Status What it means for you 
DSTU2 / STU3 Older Still found in some legacy systems, avoid for new builds 
R4 (4.0.1) Most widely deployed The default target for new FHIR integration work and most EHR APIs 
R4B Minor update to R4 Used by some newer implementation guides 
R5 Latest published release Adopt only where your partners already support it 

Older HL7 v2 messages are still common for lab results and admission events, so many FHIR integration projects also translate v2 messages into FHIR resources. 

Core FHIR Concepts Every Developer Needs 

Concept What it is Example 
Resource A unit of health data with a defined structure Patient, Observation, Encounter, MedicationRequest 
Reference A link from one resource to another An Observation’s subject points to Patient/123 
Bundle A container of many resources Search results, transactions, document bundles 
Search parameters Query filters on the REST API Observation?patient=123&category=laboratory 
Operations Server functions beyond basic CRUD Patient/123/$everything, $export 
Profiles and implementation guides (IGs) Rules that constrain resources for a use case or country US Core, ABDM (NRCES) profiles 
Terminologies Standard code systems for clinical meaning LOINC (labs), SNOMED CT (clinical terms), RxNorm (US medicines), ICD-10 (diagnoses) 
CapabilityStatement The server’s description of what it supports GET [base]/metadata 

Common FHIR Integration Patterns 

FHIR integration architecture between an app, a FHIR server and an EHR

Most FHIR integration projects follow one of these patterns. Pick the simplest one that meets the use case. 

Pattern How it works Typical use 
App launched inside the EHR (SMART EHR launch) The clinician opens your app from the EHR, it receives the patient context and reads data Clinical decision tools, AI documentation, specialty dashboards 
Standalone patient or clinician app The user logs in with the EHR or patient portal account, then your app reads their data Patient apps, remote monitoring, second-opinion services 
Backend system-to-system Your server authenticates as a registered system, with no user present Nightly sync, analytics, population health, payer data 
Bulk data export The $export operation returns large datasets as NDJSON files Data warehouses, research, AI training on de-identified data 
Write-back Your app creates or updates resources in the EHR Sending results, notes, questionnaires or appointments back 
FHIR facade over legacy systems A FHIR API is placed in front of HL7 v2 or a custom database Modernizing older clinic or lab systems 
National health network Data shared in FHIR bundles through a national framework India’s ABDM health information exchange 

One rule saves a lot of pain read before you write. Write-back usually needs extra EHR approval and testing, so many teams launch with read access first. 

Step 1: Define the Use Case and Data 

Good FHIR integration starts with a short, specific list: 

  • Who uses it: clinician, patient, or a backend system. 
  • Which resources: for example Patient, Encounter, Observation (labs and vitals), Condition, MedicationRequest, AllergyIntolerance. 
  • Read, write or both, and how often (on demand, every few minutes, nightly). 
  • Which systems: the EHRs, labs or networks you must connect to, and in which countries. 

Every resource you add means more mapping, testing and approval, so keep the first release narrow. 

Step 2: Read the CapabilityStatement and Implementation Guides 

Every FHIR server publishes what it supports at its metadata endpoint: 

curl -H “Accept: application/fhir+json” https://fhir.example.com/r4/metadata 

The CapabilityStatement tells you the FHIR version, supported resources, search parameters, operations and security endpoints. Then read the implementation guides your partners follow. In the US, most EHR APIs build on the US Core Implementation Guide in India, ABDM uses FHIR R4 profiles published for its health information exchange. These guides decide which fields are required and which code systems to use. 

Step 3: Start in a Sandbox 

Never build FHIR integration against production first. Useful places to start: 

  • Public test servers such as the HAPI FHIR public server, for learning the API with test data only. 
  • SMART Health IT’s sandbox for testing SMART on FHIR launch flows. 
  • EHR developer programs from major vendors such as Epic and Oracle Health (Cerner), which provide documentation, test patients and app registration. 

Never put real patient data on a public test server. 

Step 4: Authenticate With SMART on FHIR 

SMART on FHIR OAuth 2.0 launch flow

Most EHR FHIR APIs use SMART on FHIR for authorization. It builds on OAuth 2.0 and OpenID Connect, and comes in three common flows: 

Flow When to use it How it works 
EHR launch Your app opens inside the EHR The EHR passes a launch token, your app exchanges it for an access token with patient and user context 
Standalone launch Users open your app directly The user signs in through the EHR’s authorization server and picks or confirms the patient 
Backend services Server-to-server, no user Your system signs a JWT with its private key and exchanges it for an access token (client credentials) 

Scopes define exactly what your app can access, for example patient/Observation.read (SMART v1 style) or patient/Observation.rs (SMART v2 style). Request only the scopes you need: EHR reviewers check this. 

The general sequence for a user-facing app: 

  1. Discover the authorization endpoints from [base]/.well-known/smart-configuration. 
  2. Redirect the user to the authorize endpoint with your client ID, scopes, redirect URI and a PKCE code challenge. 
  3. Exchange the returned code for an access token (and refresh token if allowed). 
  4. Call the FHIR API with Authorization: Bearer <token> and the patient ID from the token response. 

Use a maintained SMART client library rather than hand-rolling OAuth, and never store tokens in places like browser local storage or logs. 

Step 5: Read and Write FHIR Resources 

FHIR API request for a Patient resource

The FHIR API follows familiar REST patterns. Read a patient: 

curl -H “Authorization: Bearer $TOKEN” \ 
     -H “Accept: application/fhir+json” \ 
     https://fhir.example.com/r4/Patient/123 

Search for the patient’s recent lab results, newest first: 

GET [base]/Observation?patient=123&category=laboratory&_sort=-date&_count=50 

A simplified Observation for a blood glucose result looks like this: 

{ 
  “resourceType”: “Observation”, 
  “status”: “final”, 
  “category”: [{“coding”: [{“system”: “http://terminology.hl7.org/CodeSystem/observation-category”, “code”: “laboratory”}]}], 
  “code”: {“coding”: [{“system”: “http://loinc.org”, “code”: “2339-0”, “display”: “Glucose [Mass/volume] in Blood”}]}, 
  “subject”: {“reference”: “Patient/123”}, 
  “effectiveDateTime”: “2026-11-10T09:30:00+05:30”, 
  “valueQuantity”: {“value”: 98, “unit”: “mg/dL”, “system”: “http://unitsofmeasure.org”, “code”: “mg/dL”} 
} 

To write, POST the resource to [base]/Observation, or send a transaction Bundle when several resources must succeed or fail together. Use conditional create (If-None-Exist) or your own business identifiers to avoid duplicates when requests are retried. 

Step 6: Map, Code and Validate Your Data 

Most of the real work in FHIR integration is mapping: 

  • Map your data model to FHIR resources field by field, and document every decision. 
  • Use standard codes: LOINC for labs and vitals, SNOMED CT for clinical terms, and the medication and diagnosis code systems your market requires. 
  • Match patients carefully using identifiers (MRN, national IDs where allowed), never just names and dates of birth. 
  • Validate against the right profiles with the official FHIR validator or your server’s $validate operation before you send anything to a partner. 
  • Translate HL7 v2 where needed, using a tested mapping engine rather than custom string parsing. 

Step 7: Handle Paging, Errors and Performance 

Production FHIR integration has to cope with large results and imperfect servers: 

  • Follow paging links. Search results come back as a Bundle; keep requesting the link with relation: “next” until there is none. 
  • Read OperationOutcome errors. FHIR servers explain failures in this resource; log its details for support. 
  • Respect rate limits with backoff and retries, and make writes safe to retry. 
  • Cache reference data (practitioners, locations, code lookups), but always read clinical data fresh when it matters. 
  • Use bulk export for large datasets instead of thousands of individual searches. 
  • Monitor everything: response times, error rates and token failures per partner. 

Step 8: Secure the Integration and Go Live 

FHIR integration carries protected health information, so security is part of the build: 

  • TLS everywhere, short-lived tokens, least-privilege scopes and secure secret storage. 
  • Audit logs of every read and write, linked to the user or system that made it. 
  • No PHI in application logs, error trackers or analytics. 
  • Compliance for your market: HIPAA and business associate agreements in the US, GDPR in Europe, DPDP and ABDM in India. Our guide to HIPAA-compliant app development covers the US safeguards in detail. 

Before production, most EHR vendors require app registration and review: your scopes, security approach, and a demonstration in their test environment. Plan several weeks for this, and complete testing with the clinic’s own test data before switching on real patients. 

FHIR Tools and Libraries 

Need Options 
FHIR server HAPI FHIR (open source, Java), cloud FHIR services from AWS, Azure and Google Cloud 
Client libraries HAPI FHIR client (Java), Firely SDK (.NET), fhir.resources (Python), SMART fhirclient (JavaScript) 
Validation Official HL7 FHIR validator, server $validate operation 
Testing Public test servers, SMART launcher sandbox, EHR vendor sandboxes 
HL7 v2 to FHIR Integration engines and mapping tools that convert v2 messages into FHIR resources 

Common FHIR Integration Mistakes 

  • Building to the base FHIR spec and ignoring the implementation guide your partner requires
  • Requesting broad scopes “just in case”, which slows or fails EHR review 
  • Ignoring paging, so only the first page of results is ever processed 
  • Free-text values where standard codes (LOINC, SNOMED CT) are expected 
  • Matching patients on names and birth dates alone 
  • Writing PHI into logs and error messages 
  • Leaving app registration and vendor review until the end of the project 

FHIR Integration Checklist

Use this checklist before any FHIR integration goes live. 

  • Use case, resources and read/write scope documented 
  • CapabilityStatement and implementation guides reviewed for each partner 
  • SMART on FHIR flow working with least-privilege scopes 
  • Field mappings and code systems documented and reviewed 
  • Resources validated against required profiles 
  • Paging, errors, retries and rate limits handled 
  • Duplicate-safe writes (conditional create or business identifiers) 
  • Audit logs in place; no PHI in application logs 
  • Compliance requirements and data agreements confirmed for each market 
  • EHR app registration and review completed 
  • Monitoring and alerting live for each connected system 

Frequently Asked Questions

What is FHIR integration?

FHIR integration is connecting an app or system to other healthcare systems, such as EHRs, labs or national networks, using the HL7 FHIR standard to read and write health data through a RESTful API. 

What is the difference between HL7 v2 and FHIR?

HL7 v2 is an older, message-based standard still common for lab results and admissions. FHIR is a modern, resource-based REST API using JSON, which is easier for web and mobile developers. 

Which FHIR version should I use?

FHIR R4 is the best default for new FHIR integration work, because it is the most widely deployed version and the one most EHR APIs and implementation guides use. 

What is SMART on FHIR?

SMART on FHIR is an authorization framework built on OAuth 2.0 and OpenID Connect that lets apps securely access FHIR data, either launched inside an EHR, standalone, or as a backend service. 

Can I integrate with Epic or Oracle Health (Cerner) using FHIR?

Yes. Both offer FHIR APIs and developer programs with sandboxes. Production access usually requires app registration, review and approval from the vendor and the health system. 

How long does FHIR integration take?

A focused read only FHIR integration with one EHR typically takes 6-12 weeks, including sandbox work, mapping, security and vendor review. Write-back and multiple EHRs take longer. 

Is FHIR integration HIPAA compliant?

FHIR is a data standard, not a compliance program. Your integration is HIPAA compliant only if you add the required safeguards, such as encryption, access control, audit logs and business associate agreements. 

Does India’s ABDM use FHIR?

Yes. ABDM uses FHIR R4-based profiles for sharing health records through its consent-based health information exchange. 

Why choose Briskcovey for FHIR integration?

Briskcovey is an AI-first software studio and Anthropic Claude Partner that builds and runs RazorClinic, its own clinic management SaaS. We build FHIR integrations, SMART on FHIR apps and healthcare platforms for clients in the US, UK, UAE, Australia and India. 

Work With Briskcovey 

Briskcovey is an AI-first software studio in Jaipur, India, and an Anthropic Claude Partner. We deliver end-to-end FHIR integration, SMART on FHIR apps, EHR integrations, FHIR servers and facades, HL7 v2 to FHIR mapping and ABDM integration, as part of secure healthcare platforms like our own clinic management software, RazorClinic. For the bigger picture, read our HealthTech App Development in 2026 playbook. 

Book a free 30-minute FHIR integration consultation

Kishan Kant Kataria
The Author Kishan Kataria CEO

As CEO of Briskcovey, I work closely with founders to design, build, and launch intelligent digital solutions without unnecessary complexity or long development cycles.

Developer Insights Newsletter

Stay ahead of the technology curve

Get bi-weekly technical blueprints, performance optimization guides, and architectural deep-dives delivered straight to your inbox.

No spam ever Bi-weekly deep dives Unsubscribe anytime