The TEFCA FHIR roadmap is the published plan for moving nationwide exchange under TEFCA from document queries toward FHIR APIs. It matters to anyone building an app, an EHR integration or a health information network that expects to reach records through a QHIN.
This guide walks through the roadmap's stages, explains how facilitated FHIR exchange works in engineering terms, lists the documents a team should track, and sets out what app teams and EHR teams each need to prepare. Governance and joining are covered in a separate TEFCA guide.
What is the TEFCA FHIR roadmap?
Planning FHIR exchange through TEFCA?
Agnotic builds FHIR and SMART on FHIR integrations for clients, including directory lookup, SSRAA registration and US Core data handling.
The TEFCA FHIR roadmap is a plan from ASTP/ONC and the Recognized Coordinating Entity (RCE) that sets out staged steps for adding HL7 FHIR API exchange to TEFCA. It moves from FHIR content inside a QHIN's own network, through QHIN-facilitated FHIR between participants, to FHIR between QHINs and finally end-to-end FHIR exchange.
The roadmap is a direction of travel, not a product specification. The binding detail sits in the Common Agreement, the QHIN Technical Framework and the RCE's standard operating procedures, which change on their own schedules. A team that builds against the roadmap alone will miss the rules that actually govern a connection.
Which four stages does the roadmap set out?
The roadmap sets out four stages, each building on the one before. ONC and the RCE released the FHIR Roadmap for TEFCA Exchange Version 2 in December 2023, naming the stages FHIR Content Support, QHIN-Facilitated FHIR Exchange, QHIN-to-QHIN FHIR Exchange and End-to-End FHIR Exchange.
- Stage 1, FHIR Content Support: FHIR exchange is possible within a QHIN's own network, and FHIR payloads can move between QHINs over the existing IHE-based exchange with out-of-band coordination.
- Stage 2, QHIN-Facilitated FHIR Exchange: QHINs must support facilitated FHIR API exchange, making FHIR API exchange available to Participants and Subparticipants.
- Stage 3, QHIN-to-QHIN FHIR Exchange: QHINs must support exchange between themselves through FHIR APIs.
- Stage 4, End-to-End FHIR Exchange: QHIN-brokered FHIR exchange between Participants and Subparticipants across networks.
For a builder, the important line is between Stage 2 and the later stages. In Stage 2 the FHIR call still runs between two organizations' endpoints, with the QHIN helping them find and trust each other. In Stages 3 and 4 the QHINs themselves carry FHIR traffic, which changes routing, error handling and who sees the request.
Check the RCE's site for which stage is in force before planning a release. The roadmap does not by itself commit any QHIN to a date, and each QHIN's support for a stage can differ.
How does facilitated FHIR exchange work?
Facilitated FHIR exchange lets one TEFCA participant call another participant's FHIR API directly, with the QHIN framework providing endpoint discovery and the trust needed to register and authorize. The data flows between the two endpoints rather than through the QHIN.
An ASTP/ONC blog post published on 3 January 2024 said ONC and the RCE expected facilitated FHIR exchange as early as the first quarter of 2024, connected to the release of Common Agreement Version 2, and that the TEFCA FHIR implementation guide relies on the HL7 Security for Scalable Registration, Authentication, and Authorization (SSRAA) implementation guide, version 1.0.
Directory, trust and authorization
Three building blocks carry a facilitated request. Each needs its own code path and its own failure handling.
- Directory: the RCE directory lists participants and their FHIR endpoints, so the requesting system looks up where to send a call instead of hard-coding partner URLs.
- Trust: SSRAA, which grew out of the UDAP work, uses certificates and signed software statements so a client can register with a server it has never met.
- Authorization: after dynamic registration the client gets an OAuth access token, such as a client credentials grant for system-to-system exchange, and asserts the exchange purpose the request is made for.
- Request: the client queries the responder's FHIR API, typically searching for Patient and then reading the clinical resources the exchange purpose allows.
Patient matching does not go away with FHIR. The requester still sends demographics to find a patient at the responder, and both sides need rules for no match, several candidates and a match that later proves wrong.
Which TEFCA documents should an engineering team track?
An engineering team should track the Common Agreement, the QHIN Technical Framework, the Facilitated FHIR Implementation SOP and the RCE directory guide, because together they define what a connection must do. Each has a version number and a change process.
As of this writing, the RCE resources page lists Common Agreement Version 2.1, QHIN Technical Framework Version 2.1 and the Facilitated FHIR Implementation SOP Version 2.0. Record the version each release of your software was built against, and subscribe to RCE updates so a change does not arrive as a surprise from a QHIN.
Read the SOPs closely. They carry operational detail that never appears in the roadmap, such as which security profiles are expected, how endpoints are published to the directory and what timelines apply to QHINs and their participants.
Keep a short internal summary of each document that names the clauses your code depends on. When the RCE publishes a new version, compare only those clauses first, then read the rest for anything new.
What changes for an app or product team?
For an app team, TEFCA FHIR means a path to records at organizations it has no direct contract with, but only through a participant relationship and only for an allowed exchange purpose. The product has to prove who it is, why it is asking and which patient it means.
Build the client to discover endpoints at run time from the directory, register dynamically with SSRAA, and store each responder's registration and token details separately. Hard-coding a handful of partner endpoints works in a pilot and breaks as soon as the network grows.
Expect variety in the data. Responders will share US Core-based resources, but coverage, coding and the depth of history differ from one site to the next. Normalize on receipt, keep the source of every resource and show users where data came from.
Plan for partial results. A query that fans out to many responders will get some answers quickly, some slowly and some not at all. The user interface should show what has arrived and what is still pending, rather than waiting for a full set.
Testing before the first live call
Testing a TEFCA FHIR client needs more than a FHIR sandbox. Ask the QHIN or participant for a test environment with a directory, test certificates and responders that return realistic US Core data, and script the unhappy paths: an expired certificate, a rejected registration, a token refused for the stated exchange purpose, a patient with two candidate matches and a responder that times out.
Keep those scripts in the build pipeline. Certificates expire and SOPs change, and a regression suite that exercises registration and authorization catches both before users do.
What changes for an EHR or health system team?
For an EHR or health system team, TEFCA FHIR adds a responder role: publishing a FHIR endpoint, accepting registrations from parties it does not know, and answering requests under the Common Agreement. It also adds a requester role for pulling outside records into the chart.
A health system may rely on its EHR vendor for the responder endpoint. Even then, the organization needs to know which endpoint is published under its name, which exchange purposes it answers and how requests are logged, because it remains accountable for what it shares.
The requester side is where integration work lands. Outside data needs reconciliation before it enters problem lists, medication lists and allergies, and clinicians need to see the source. A FHIR feed that drops unreconciled records into the chart creates more work than it saves.
Audit logging deserves its own design on both sides. Record the requester's identity from its registration, the exchange purpose asserted, the patient matched, the resources returned and the time, so privacy and compliance teams can answer questions about any disclosure without reconstructing it from server logs.
A readiness checklist for TEFCA FHIR
This checklist turns the roadmap into engineering tasks. It applies to both app and EHR teams, with the roles noted where they differ.
- 1. Relationship: confirm which QHIN or participant you connect through, which exchange purposes they support and which roadmap stage they offer today.
- 2. Documents: record the Common Agreement, QTF and SOP versions you build against, and assign someone to watch for RCE updates.
- 3. Directory: build endpoint lookup against the RCE directory and cache it with an expiry, never as a static list.
- 4. Trust: implement SSRAA registration with certificate handling, and test certificate expiry and revocation before go-live.
- 5. Authorization: support the token flow and exchange purpose assertion your SOP requires, and log both on every call.
- 6. Matching: define demographic match rules, handling of multiple candidates and a process for correcting wrong matches.
- 7. Data: validate incoming resources against US Core, normalize codes, keep provenance and reconcile before writing to the chart.
- 8. Responder (EHR teams): confirm which endpoint is published for your organization and what it returns for each exchange purpose.
- 9. Monitoring: track response times, failures and empty results by responder, so support can tell a network problem from a partner problem.
How Agnotic can help
TEFCA FHIR work combines three hard parts: dynamic trust between strangers, patient matching across networks and messy data from many responders. Agnotic Technologies builds those parts for clients: directory-driven clients, SSRAA registration and token handling, matching rules, US Core validation and the reconciliation step that keeps outside data from cluttering the chart.
Agnotic works alongside the client's QHIN or participant and its EHR vendor, building to the SOP versions in force and keeping the code ready for the next roadmap stage.
Build TEFCA FHIR exchange with Agnotic
Explore Agnotic's FHIR and SMART on FHIR development work, or browse the FHIR articles hub.
Related reading on Agnotic
Continue with the TEFCA guide, SMART on FHIR scopes, US Core and FHIR adoption.
