Working with the FHIR API in Practice: Epic, athenahealth, Medplum

In our experience, the vendor layer around the standard causes most of the delays. We built an EMR interoperability layer for a US-based HealthTech company. It connects 10+ systems, including Epic, athenahealth, and Medplum, from one codebase. We also deliver on Medplum, an open-source FHIR platform. Everything below comes from that work.

In our new article, we cover the business problems a FHIR API solves, real FHIR API examples, and the pitfalls that stall launches. We also compare Epic, athenahealth, and Medplum, and show how to plan an integration that holds its dates.

Key Takeaways

• A FHIR API gives healthcare systems one common way to exchange data. It removes the need for a custom connection to every system.

• The standard is shared, but access rules, approvals, and coverage differ by vendor. Plan for those differences to keep your launch on schedule.

• Epic starts with registration and approval. athenahealth runs its own developer program. Medplum has no approval gate, but you run or buy the infrastructure.

• FHIR API integration projects slip when one estimate covers every vendor.

• Security and audit records need to be designed in from the start. FHIR does not provide them on its own.

What Challenges Does Working With the FHIR API Solve?

Working with the FHIR API solves one big problem. Healthcare data sits trapped in separate systems. A shared API lets your product reach that data without a custom build for each system.

What a FHIR API does

A FHIR API is a shared way for software to request and send healthcare data. Patients, appointments, and lab results all travel as FHIR resources. The data moves as JSON over standard web requests.

Each server resource, such as a Patient, supports the same basic actions. You can create, read, update, delete, and search. HL7 FHIR gives every system one vocabulary for standardized data exchange. That is how software systems communicate in one format.

We assume you know the standard, so we focus on what it changes for your product. For healthcare organizations, it enhances healthcare data management. Better healthcare data management starts when patient data, clinical data, and billing or administrative data follow the same rules.

Data stuck in separate healthcare systems

Most health organizations run several systems that were never built to talk to each other. Clinicians re-enter data, and patients fill in the same form twice. Products that depend on that data cannot launch.

The API gives your product one way to read and write that data. It breaks down the silos without replacing the systems underneath. When healthcare systems communicate through the same API, teams can streamline data exchange. They can also keep their existing data model and map it to FHIR once, instead of once per customer.

Rebuilding the same integration for every customer

Without a shared standard, every new customer means a new integration project. FHIR cuts that cost because the data model stays familiar from one system to the next. A large part of the work becomes reusable.

That is how we connected 10+ EMRs from one codebase. It is also why healthcare systems connect through one layer instead of dozens of one-off projects.

Patient access and regulatory pressure

Patients now expect to see their own records in an app, and regulation backs them up. FHIR makes data access simpler for patients and for the mobile apps they use to pull their medical history together. In the US, the 21st Century Cures Act pushes health IT vendors toward standardized APIs for patient access. Payers face their own FHIR API deadlines.

Teams that already work with FHIR resources are better placed to meet regulatory compliance requirements. The standard also covers administrative and financial processes, such as healthcare services reimbursement. So the same approach reaches beyond clinical care. Reliable healthcare interoperability solutions plan for evolving healthcare interoperability standards, because versions and profiles keep changing.

What FHIR API Examples Show the Value in Practice?

The clearest FHIR API examples come from products that would not exist without a shared way to exchange data. Here are three that we see in our work.

Patient intake delivered into any customer's EMR

The platform we mentioned above captures patient intake and referral details. It then delivers them into each customer's Electronic Medical Record (EMR). Some of those systems expose modern FHIR APIs, and the rest need other routes.

One codebase serves them all. The client can onboard a new health system without a custom build. Our layer actively connects healthcare systems that speak FHIR and those that do not.

A preventive care platform built on Medplum

We built a preventive care platform on Medplum with a Health Gorilla integration for early cancer detection. Health Gorilla supplies patients' records from external sources, and the whole product is HIPAA-compliant. Patients book screenings, see their records, and consult physicians in one place. Doctors review cases and order tests.

Medplum is FHIR-native, so the team spent its time on the product experience. It did not need to design custom data models.

Patient apps and tools that live inside the EHR

Two more patterns are common. Patient-facing apps pull records from several providers into one view. Third-party tools launch inside an EHR through SMART on FHIR. In both cases, the API lets a small team add value on top of systems it does not control.

CDS Hooks go one step further. They provide real-time clinical recommendations inside EHR workflows. Remote monitoring works the same way, with device data flowing back into the patient record. Some systems also return an international patient summary, which helps when patients move across borders.

What Pitfalls Come With Working With the FHIR API?

The pitfalls start when a team treats "FHIR" as a promise that every integration works the same way. Vendor pages often promise seamless data exchange and FHIR support. Yet each vendor decides who gets access to its healthcare data, how, and with what limits.

Teams find out after the timeline is set. Often they are working with FHIR API sandboxes that look nothing like production.

Planning one timeline for every vendor

A single estimate for "the FHIR integration" hides several separate efforts. Approval, access, and coverage differ by system. Estimate each vendor on its own, and put approval lead time on the critical path.

Assuming every system supports the same data

One system may let you read a type of record in its FHIR resources but not write it. Another may not expose it at all. Older systems and legacy data add another layer, because some customers still send files or use proprietary connections.

We recommend a simple coverage checklist for every data type your product needs. Complete it during discovery, before you promise a feature to a customer. Typical items on that checklist are the ability to:

• Record vital signs and record clinical notes.

• Record smoking status, record pregnancy status, and read an outside record pregnancy status.

• Record health concern entries, record an encounter diagnosis, and read an outside record encounter diagnosis.

• Record screening assessment results, patient-reported surgical history, and a code status questionnaire.

• Record sexual orientation and other social history fields.

• Exchange communication records used for customer relationship management and community resource communication.

Any of these can be readable on one system and missing on another.

Trusting the sandbox

A sandbox proves your requests are well formed. It does not prove your product works on messy production data. Real data has merged records and missing fields. Reserve time for a pilot in a real customer environment.

Treating security and compliance as automatic

FHIR does not make data sharing secure on its own. All production healthcare data exchange should use SSL, now usually TLS. Authorization should use OAuth 2.0 for secure access.

Access controls, encryption, and audit logs still need to be designed and tested. Any API that handles patient data in the US must also comply with HIPAA regulations. Every health system customer will ask about these controls early.

We build HIPAA-ready software and help teams stay compliant. We do not certify integrations or act as an auditor.

Hitting limits nobody planned for

FHIR supports both synchronous and asynchronous interactions. A lookup returns right away, while a Bulk FHIR export runs in the background. Every system has performance and rate limits, and large request volumes can slow a product down.

In our interoperability project, the platform had to deliver each document within 30 seconds. There was no way to report back to the user afterward. That constraint shaped the whole design, and we built for it from day one.

What Will Your Engineers Ask About Before Launch?

The standard defines a few behaviors that vendors implement in different ways. Your engineers will ask about them early. Here are the four areas we check first.

Versions and updates

Whenever a server supports versions, it keeps each resource's version history. Some also support accessing previous versions. Some servers limit version-specific patch operations.

Version-aware updates and version conflict management stop two systems from overwriting each other. Ask each vendor how it tracks a created resource version.

Identifiers and duplicate records

A server may support client-defined IDs. Another may use a server-assigned ID search pattern, where you search before any create. And this is how clients creating duplicate resources slip in after a retry.

A create interaction creates a new record every time. Retrying blindly is a common web programming error. The generic server frameworks underlying most web apps do not protect you here.

Search and batch requests

Not all servers supporting search handle parameters the same way. Differentiate search parameters defined by the standard from the ones a vendor adds. References can use an absolute or relative URL, and vendors differ on which they accept.

Duplicate patients cause trouble here, because each Patient record should map to one real-world corresponding resource, the actual person. Check whether one request can delete multiple resources. Batch requests let a system perform multiple operations in one call.

Errors and status codes

Errors follow the underlying HTTP protocol. Most are normal HTTP errors related to a missing record or a bad request. Servers return specific HTTP status codes, such as 404 for a missing record.

Detailed error messages describing the problem help you tell a missing record from a malformed one or one rejected by server business rules. The common HTTP status codes are the same across vendors. Even the MIME type parameter that selects the FHIR version can vary.

Test each of these areas against every system before launch.

How Does the FHIR API Differ Across Epic, athenahealth, and Medplum?

All three give you the same data model and a different path to using it. Epic and athenahealth gate access through their own programs. Medplum removes the gate and hands you the infrastructure. Here is what that means for a business plan.

Epic: approval first, then integration

Epic's FHIR API starts with registration and approval. The practical work begins before your first production use. You register your app and request the data access you need. Then you go through the vendor and health system process.

The program has been known for years as App Orchard. Epic's developer documentation is the place to confirm the current name and steps.

Plan the approval path in parallel with development. In our experience, teams that leave it to the end are the ones whose launch stalls. Access also tends to be narrower than requested. The same Epic software can be configured differently from one health system to the next.

athenahealth: its own program, its own coverage

athenahealth exposes its FHIR API through its own developer and marketplace program. It has its own review and its own coverage. A team that just finished an Epic integration should not assume the same steps, timeline, or list of supported data.

Check the current requirements in athenahealth's developer documentation. Do it before you commit to a date.

Medplum: no approval gate, more to operate

Medplum's API is open source and can be self-hosted. That removes the vendor approval step. The trade-off is that you run the infrastructure yourself or buy a managed option.

We are one of the few outsourced teams with active Medplum experience in production. Medplum is a partner platform for us, so treat this as a look at starting points. It ranks nothing.

Medplum is the faster start when you want to prove out a product before approaching larger EHR vendors. It does not replace an EHR connection when your customers run on Epic or athenahealth. It also works as the base for custom EHR and EMR development when a product needs its own record layer.

Side-by-side comparison

How Do You Make a FHIR API Integration Work in Practice?

The integrations that hold their dates share one trait. They treat the standard as the shared part and handle each vendor's differences separately. Here is how we approached it in the interoperability project.

Keep the shared part shared

We wrote one integration per system. Each one covers only what is unique to that vendor and inherits everything else. A shared base serves the systems that speak FHIR, including Medplum. Systems with older file-based or proprietary connections get their own thin layer.

That is why the same product connects to 10+ EMRs without a rebuild for each.

Treat customer differences as settings

Two health systems can run identical software and still expect different configuration and credentials. We stored those per-client differences as data. A new clinic now goes live through configuration instead of a code change. That removed the need for a separate version of the product per customer.

Make every delivery traceable

Once a document leaves the platform, nothing tells the user what happened on the other side. We log every delivery so each one can be traced. That record supports a compliance review.

When you cannot see what happened downstream, the audit trail is your proof.

A short plan you can use

Here is the order we recommend:

• List every system your customers run and which of them offer a FHIR API.

• Estimate approval, access, and data coverage for each vendor separately.

• Start approval conversations first and development in parallel.

• Check coverage for every data type before you commit a feature to a date.

• Pilot in a real customer environment in addition to the sandbox.

• Design security and audit records from the first sprint.

Follow these steps, and most surprises show up while there is still time to plan around them.

Final Thoughts: Plan for the Differences, Reuse the Standard

Working with the FHIR API in practice means treating FHIR as the shared layer. Plan each vendor's access, approvals, and coverage separately. Build the common work once and expect the surrounding process to differ every time. Teams that plan this way keep their launch dates.

Where is this heading?

• Vendor size will keep shaping access. An older ONC data brief reported by TechTarget found that 79% of hospitals using bigger EHR vendors offered patient data access through an app. The figure was 17% for mid-level EHRs and 4% for bottom-tier EHRs.

• Regulation and innovation will keep driving adoption. Statista's 2025 survey of FHIR experts ranks them as the two top drivers of FHIR adoption worldwide.

• Large-scale data sharing will become routine. Bulk FHIR moves large datasets between organizations. It will shift from a special case to the default as payers and providers exchange more data.

Plan for uneven access among the vendors you target, and budget for the growth in data volume.