How to Implement FHIR

How do you implement FHIR on a first project?

Implementing FHIR on a first project means choosing one bounded use case, naming the implementation guide and version that governs it, picking a server or EHR API to build against, setting up SMART on FHIR authorization, and proving conformance with the HL7 FHIR Validator and an Inferno test kit before any partner connects.

The order matters because each decision narrows the next. The use case decides the guide, the guide decides what the server must support, and the server decides how authorization and testing are wired.

It also matters which side you are building. A team can build a FHIR client that reads from an EHR, a FHIR server that exposes its own data, or both. The plan below works for either side, but the test tools and the definition of done differ.

Which first use case should a FHIR team pick?

Pick a use case that reads a small set of resources for one type of user at one site. Reading is simpler than writing, one user type means one launch pattern, and one site means one set of credentials and one approval process.

• Good first scope: A clinician-facing app that reads Patient, Condition, Observation and MedicationRequest for the patient already open in the EHR.
• Also reasonable: A nightly backend job that pulls lab Observations for a list of enrolled patients into an analytics store.
• Too large for a first project: Two-way sync of orders and notes across several EHR vendors, with a patient app on top.
• Scope brief: One page naming the user, the trigger, the resources, read or write, the target system and what counts as done.

Writing back needs a separate check. Under 45 CFR 170.315(g)(10), certified EHRs must offer a standardized API for reading patient and population data, not for writing it. Any write, such as filing a note or a result, runs through vendor-specific APIs or an HL7 v2 interface, so a first project that needs one should confirm it with the vendor before the scope is signed.

Name a clinical owner for the use case as well as a technical one. The clinical owner decides which data is good enough to show, which is a question no conformance test answers.

Which implementation guide governs the data?

In the United States the starting guide for clinical data is HL7 US Core, which profiles FHIR R4 resources to carry USCDI data. Domain guides sit on top of it for specific work, and a first project should name one primary guide and its exact version.

• Clinical data exchange: US Core. The ASTP/ONC HTI-1 rule set US Core 6.1.0, USCDI v3 and SMART App Launch 2.0 as the baseline for certified APIs from 1 January 2026.
• Payer workflows: The HL7 Da Vinci guides, such as CRD, DTR and PAS for coverage rules and prior authorization.
• Oncology: mCODE, the HL7 guide that defines FHIR profiles for structured cancer data.
• Population exports: The Bulk Data Access guide, which defines asynchronous $export for groups of patients.
• Authorization: SMART App Launch, which every guide above assumes for app access to protected data.

Record the guide, its version and the profiles in scope in the scope brief. Version choice, Must Support handling and required searches are where US Core work gets detailed, and the related reading at the end covers them.

Which FHIR server or API should you build against?

Build against the system the data will actually come from. If an EHR holds the data, its FHIR API and sandbox are the target. If your product holds the data, choose between an open-source server, a managed cloud FHIR service or a FHIR facade over an existing database.

• EHR vendor API: Use the vendor's developer program and sandbox, for example fhir.epic.com for Epic. The vendor decides which resources, searches and write operations exist, and its CapabilityStatement lists them.
• HAPI FHIR JPA server: An open-source Java implementation of FHIR that deploys as a database-backed server. The team owns hosting, upgrades, indexes and performance.
• Managed cloud FHIR service: The major cloud providers offer hosted FHIR stores. Hosting is handled, but the team still owns profiles, terminology, access rules and the business associate agreement with the provider.
• FHIR facade: An API layer that translates FHIR requests into queries on an existing database or HL7 v2 feeds. It avoids copying data but puts mapping and search logic in the team's own code.

Read the CapabilityStatement first, whichever option you choose. It is the server's machine-readable list of supported resources, interactions, search parameters and guides, and it answers most early questions about fit.

For a self-hosted server, put load testing with production-like volumes in the plan from the start. Search speed on a database-backed FHIR server depends on its indexes, and a test set of five sandbox patients hides that cost.

How should authorization work from day one?

Authorization should use SMART on FHIR from the first sprint, because certified EHR APIs expect it and adding it late means reworking the client. Choose the launch type that matches the user, request the narrowest scopes, and keep tokens on the server where possible.

• EHR launch: The app opens inside the EHR, and the launch passes the current patient and user as context.
• Standalone launch: The user opens the app directly and signs in through the EHR's authorization server.
• Backend services: A server-to-server client authenticates with a signed JWT and an asymmetric key pair, with no user present.
• Scopes: Request read scopes only for the resources in the scope brief. Newer SMART App Launch versions add granular scopes, such as Observation limited by category, which make narrow requests easier.

HIPAA's technical safeguards ask for unique user identification, audit controls and authentication, but leave the protocol to the team. SMART on FHIR covers the authentication side; the audit side is the team's job, so log each token grant and API call with the user and patient involved, and keep PHI out of general application logs.

Register test clients early. App registration and redirect URI setup with an EHR vendor or a health system can take longer than the code, and it blocks every later test.

How do teams test FHIR before going live?

Teams test FHIR in three layers: the HL7 FHIR Validator checks each resource against its profiles, an Inferno test kit checks server or client behavior, and a pilot with real data checks what neither tool can. All three should pass before a partner sees the system.

• 1. Validate resources: Run the HL7 FHIR Validator, published as validator_cli.jar through the GitHub releases of the org.hl7.fhir.core project, with the guide package and version named in the scope brief.
• 2. Build synthetic patients: Create test patients that fill every profiled element in scope, plus sparse patients with missing data and long histories.
• 3. Run Inferno: Inferno is the ASTP/ONC open-source tool for automated FHIR conformance tests. Its US Core Test Kit and ONC (g)(10) Standardized API Test Kit can run on a local machine or a shared copy behind the firewall.
• 4. Automate: Put the validator and the chosen Inferno kit in continuous integration, so a change that breaks conformance fails the build.
• 5. Sandbox: Repeat the key scenarios in the target EHR's sandbox and note each place its behavior differs from the guide.
• 6. Pilot: Test with real records at one site, watching paging, unmapped codes, token expiry and response times.

What a first FHIR project plan looks like

A first FHIR project plan fits on one page and names an owner for each decision. Use this checklist as the outline and fill each line before the first sprint ends.

• Scope brief: User, trigger, resources, read or write, target system and definition of done, signed by the clinical and technical owners.
• Guide and version: Primary guide, version, profiles in scope and the terminology releases it depends on.
• Target system: EHR sandbox or server choice, CapabilityStatement reviewed, gaps against the scope listed.
• Authorization: Launch type, scopes, client registration, token storage and audit logging design.
• Mapping: Source fields to profile elements, local codes to LOINC, SNOMED CT or RxNorm, and a written rule for each missing element.
• Testing: Validator configuration, synthetic patients, Inferno kit, CI job and sandbox scenarios.
• Compliance: Business associate agreements with every host and vendor that touches PHI, and the HIPAA risk analysis updated for the new data flow.
• Go-live: Pilot site, monitoring for errors and token failures, and a rollback plan.

Where do first FHIR projects stall?

First FHIR projects stall on decisions that were never written down, more than on code. These failure points are worth checking against the plan before build starts.

• No version pin: The client is built against one US Core version while the partner server runs another, so profiles and searches disagree.
• Sandbox treated as production: Sandbox patients are clean and short; real records carry gaps, local codes and histories long enough to need paging.
• Assumed write access: The design files data into the EHR, and the vendor offers only reads for that resource.
• Oversized scope requests: The app asks for access to everything, and the health system's security review slows or refuses the registration.
• Late validation: The validator runs for the first time just before go-live and returns hundreds of errors at once.
• Server chosen before the guide: A server is picked for familiarity and then lacks a search or operation the guide requires.
• No terminology owner: Local codes reach the API unmapped, and the receiving system cannot use them.

How Agnotic can help

A first FHIR project goes faster when the scope brief, guide pin and test setup exist before the integration code. Agnotic Technologies builds first FHIR projects for digital health companies and hospital IT teams, starting with that plan and carrying it through to a pilot site.

Agnotic writes the scope brief with the client's clinical owner, reviews the target CapabilityStatement, sets up SMART on FHIR authorization, maps source data to the chosen profiles and puts the HL7 FHIR Validator and Inferno in CI, so the client's team inherits a tested build and the plan behind it.

Sources

• HL7: US Core Implementation Guide
• ASTP/ONC: Standardized API for patient and population services, 45 CFR 170.315(g)(10)
• ASTP/ONC: Inferno FHIR testing and test kits