Guide to HL7 / FHIR

Connecting to EHR Systems Using FHIR APIs in Iguana

Integrating with enterprise EHR systems involves more than simple RESTful calls. While FHIR provides a consistent standard for exchanging healthcare data, production EHR APIs introduce additional requirements for registration, authentication, and vendor-specific conventions.

Example workflow Send a patient admission to an EHR using a FHIR API

Patient Admission

ADT^A01
LLP Feed

Iguana

Integration Engine

HL7
(v2)
FHIR
(JSON)

FHIR API

REST / JSON

EHR System

Epic · Athenahealth · eClinicalWorks

Overview

Iguana is designed to manage these realities by combining secure communication, flexible scripting, and pre-built adapters for major EHR vendors, including Epic, Athenahealth, and eClinicalWorks.

FHIR as the Foundation for EHR Connectivity

FHIR defines how healthcare systems expose structured data through standardized REST endpoints. In production environments, these APIs allow external systems to exchange patient, encounter, and observation information securely and consistently.

EHR vendors build on this foundation by publishing their own FHIR implementations. While the data model remains consistent, differences appear in how each vendor handles authentication, endpoint configuration, and supported resources. Iguana bridges these variations by providing adaptable components that connect securely and predictably across systems.

Authentication and Authorization

Production FHIR APIs rely on secure authentication and authorization to control access to sensitive data. Most vendors follow the SMART on FHIR specification, which extends OAuth 2.0 for healthcare use cases.

Common authentication patterns include server-to-server credentials, user-based authorization, and token-based backend services. These flows determine how an application obtains and maintains access to protected data.

Common Authentication Patterns

Flow TypeCommon UsageKey Details
Client CredentialsServer-to-server communicationUses a client ID and secret to obtain an access token.
Authorization CodeUser-initiated applicationsUser signs in through the EHR portal, then the application exchanges the code for a token.
Backend Services (JWT)System-to-system servicesClient signs a short-lived JSON Web Token with a private key and exchanges it for an access token.

Iguana supports each of these flows through configurable scripts that securely handle credentials, store tokens, and automatically refresh them before expiry. This keeps operations uninterrupted while meeting security expectations.

Managing FHIR Data Exchange

Once authenticated, systems communicate with the EHR FHIR server using standard CRUD operations (Create, Read, Update, and Delete). In practice, these interactions require additional handling for authentication headers, content types, and rate limits.

Examples of common workflows

Patient demographics

Retrieving patient demographics for synchronization across internal systems.

Clinical observations

Posting lab or device results to an EHR Observation endpoint.

Encounter information

Updating encounter information to maintain longitudinal patient records.

HL7-to-FHIR transformation

Transforming HL7 v2 messages into FHIR resources for downstream use.

Iguana's net.http and json modules, along with its translation and routing capabilities, give developers precise control over these exchanges. Requests, responses, and transformations can be inspected, logged, and adapted for production-level reliability.

Vendor Variations and Real-World Considerations

Even with FHIR's shared foundation, no two EHR implementations behave the same. Successful integration requires understanding both technical and operational nuances that differ between vendors and even between installations of the same system.

Between vendors

  • Authentication flows and token lifetimes vary
  • Endpoint URLs and required claims differ
  • Resource coverage may not include every FHIR entity
  • Custom extensions and vendor-specific fields are common

Within a single vendor

  • Sandbox and production environments can behave differently
  • Application registration processes may vary by organization
  • Required scopes and audiences can differ between installations

These variations are shaped by how major vendors interpret and extend the FHIR specification. For example:

  • Epic often requires SMART on FHIR scopes, signed JWT authentication, and organization-specific base URLs.
  • Athenahealth combines FHIR endpoints with proprietary REST APIs for scheduling and chart data, each with separate authentication flows.
  • eClinicalWorks may provide multiple base URLs across practice modules and blend FHIR with hybrid endpoints or custom data extensions.

Iguana provides a unified scripting layer to handle these differences through configurable logic and reusable adapters. As support for additional vendors expands, integrations can adopt new EHR APIs using the same architecture without rebuilding existing infrastructure or workflows.

Pre-Built EHR Adapters

Iguana includes pre-built adapters for many EHR systems, including Epic, Athenahealth, and eClinicalWorks to name a few. Each adapter implements authentication, token handling, and request management patterns tailored to the vendor's platform.

EHR VendorDescriptionIguanaX Adapter
EpicOAuth 2.0 with JWT-based client assertion, including automatic token management and built-in support for create, read, search, and extended FHIR operations.Epic FHIR Adapter
AthenahealthOAuth 2.0 system-level authentication with automatic token renewal and unified request handling across AthenaOne and FHIR APIs.Athenahealth Adapter
eClinicalWorksOAuth 2.0 (JWT) authorization with automatic token management and integrated support for create, read, and search FHIR operations, depending on sandbox permissions.eClinicalWorks Adapter

Adapters handle recurring tasks such as credential exchange, endpoint configuration, and error reporting. They can be extended or combined with new adapters as Iguana's library of EHR integrations grows, providing a scalable foundation for connecting to a wide range of systems.

Managing Environments and Configuration

Production EHR systems are typically divided into sandbox (development), certification (testing), and live (production) environments, each requiring unique credentials and endpoints. Iguana supports per-environment configuration, allowing integrations to move through development and validation stages without modifying underlying code.

Best practices include

  • Keeping credentials and tokens secure and isolated from scripts
  • Parameterizing base URLs and configuration values for each environment
  • Logging and auditing configuration changes for traceability

This approach ensures consistent behavior across environments, reduces deployment risk, and simplifies long-term maintenance for production integrations.

Monitoring and Reliability

Reliable data exchange requires continuous monitoring and error visibility. Iguana provides built-in tools for tracking:

Connection health

Connection status and token validity.

Performance

Message throughput, latency, and success rates.

API errors

HTTP response patterns and error conditions.

Audit trails

Detailed transaction logs for auditing and compliance reporting.

Integrated alerts and dashboards allow administrators to identify issues proactively and maintain consistent data flow between systems.

Common Integration Patterns

Production FHIR integrations often extend beyond single API calls. Common use cases include:

Patient synchronization

Pulling updates from an EHR and distributing across internal systems.

Observation posting

Submitting structured clinical results from devices or labs.

Encounter updates

Mapping and updating visit data using a mix of HL7 and FHIR.

Hybrid orchestration

Combining FHIR APIs with other data formats to support billing or scheduling workflows.

Iguana's modular channels and scripting environment allow these patterns to scale from individual connections to multi-system interoperability across an enterprise.

Summary

FHIR provides the shared language for healthcare data exchange, while production EHR integrations add authentication, authorization, and operational complexity. Iguana unifies these layers through secure token handling, adaptive data exchange, and pre-built adapters for many EHR vendors. Its flexible architecture and expanding adapter library make it well suited for organizations seeking reliable, scalable interoperability across healthcare systems.

Next: Explore More About FHIR

Now that you’ve seen how FHIR APIs connect real EHR systems, you can return to the main FHIR Hub to explore other areas such as FHIR resources, profiles, and data models.

Continue reading: FHIR Hub Overview →