XDS Explained: Build a Working Document Exchange on Your Laptop
A simple XDS tutorial: understand Registry vs Repository and run the core XDS flow end-to-end with the NIST XDS Toolkit, Docker, and Postman.
I get asked this a lot, “How do I get all of a patient’s data?”
The answer depends mainly on one thing, are you covered by HIPAA?
Most people think of HIPAA as the “keep everything secure” law. But really, its focus is on portability, that is, moving health records between organizations without burdening the patients. Once you know where you stand on HIPAA, the rest of the process follows.
If you’re not a HIPAA-covered entity
Life insurance companies, Clinical or Contract Research Organizations (CROs), pharmaceutical companies, law firms, none of these entities are covered by HIPAA. A common one that surprises people is that health insurance is HIPAA-covered. If you fall outside HIPAA coverage, you are relying on the patient to get you access to their data.
The first thing you have to figure out is whether the patient knows where they’ve received care, who their payers are, and whether they have their login credentials.
If they do, you’re in good shape. Payers expose FHIR APIs under CMS-9115. The patient can log in, see a consent screen, approve, and you get the data. Same story on the provider side. All EHRs under ONC certification have to expose patient data via FHIR under the G10 requirement. The patient goes to their EHR portal, consents, and the data comes through.
If they don’t know all their providers or might be missing some, TEFCA IAS is a good backup. The patient uploads a government ID, authenticates at IAL2, and you can query the network for everywhere they’ve received care.
One caveat: Epic as of today still requires the patient to log into MyChart and consent separately, even through TEFCA. And TEFCA IAS is provider-only, you won’t get claims or financials through it.
There’s also Apple Health, which is more useful than people give it credit for. You’d think it’s just steps and heart rate, but if the patient has connected their EHRs inside Apple Health, you can pull all of that through HealthKit APIs without integrating with each EHR yourself. Sleep, labs, clinical records, it’s all there. This is especially relevant if you’re in mental health or chronic care, where things like sleep patterns and activity actually matter clinically.
The manual fallback is the HIPAA release form. The patient signs off, and you go to each covered entity, including providers and payers, and request their records. Most have a data release department. Some have a portal. Some will email it. Some will send you a CD. We’ve even received floppy disks. It works, but it’s slow (can take 30-60 days) and inconsistent and they do charge per page in a lot of cases.
If you are a HIPAA-covered entity
Worth noting: if you’re a health tech company serving a HIPAA-covered entity and you have a BAA with them, you fall under this category too.
If you’re a provider with a valid National Provider Identifier (NPI) and legitimately providing care, you can query patient data directly through a Health Information Exchange (HIE) without going back to the patient each time. And I say legitimately because there have been cases of people misusing this, there’s a whole lawsuit between Epic, Particle Health, and Health Gorilla about exactly that.
You can go through a vendor like Particle Health or Health Gorilla, which make things simpler, or go directly to something like CommonWell Health Exchange, which is cheaper but requires more integration work on your end. You give them basic demographics, name, date of birth, gender, address, and they query their network and return whatever records they can find. In practice it’s not as comprehensive as the patient-mediated FHIR APIs, and the data usually comes back as CCDA rather than FHIR, so it’s older and a bit less complete. You’ll get a good summary though, including clinical notes and a fair amount of unstructured data. If you’re providing care and just need to know what happened to this patient and where they’ve been, that’s usually enough.
TEFCA Treatment use works similarly, with one difference from the IAS path: if you have a Treatment use case, Epic won’t ask the patient to re-authenticate. That’s a meaningful difference in practice.
If you’re integrated directly with the EHR, you have a few options. You can build a SMART on FHIR app on the practitioner-facing side, practitioners log in and you get access to their patients. Or you can use bulk FHIR APIs with a configured group ID to pull at scale, though that takes longer to set up inside the EHR. If Epic is involved and you’re okay with practitioner-mediated access, CDS Hooks is a useful pattern, it fires when a chart is opened, so you get a list of active patients without having to poll, and then you use the provider APIs to fetch their data.
On the older side of things: HL7 v2 feeds still go a long way (and are more robust). You can tap directly into an EHR’s HL7 v2 feed, and there are vendors and integration engines in the middle (Redox, Mirth Connect, Rhapsody) that handle the conversion. Apache Camel is solid too if your stack is Java. Most EHRs also support CCDA, either via API or FTP. Also, EDI X12 is worth knowing about if you’re doing anything on the revenue cycle side, it’s how claims flow between EHRs and clearinghouses, and you can position yourself as a proxy in that pipeline.
For database-level access: if the database is within reach and it’s something standard like MySQL or Postgres, Change Data Capture is a clean way to get a real-time feed of every change. Epic also has Clarity, which lets you run specific queries against their data model instead of doing a full dump. If you want to see what that looks like, the Tuva Health GitHub has connectors for this that are worth checking out.
If you’re a payer
Two things coming in 2027 that are worth tracking: DaVinci payer-to-payer FHIR APIs, which will let payers query other payers for patient data, and DaVinci provider access APIs, which will let providers query payer data for patients under their care. Both are still early. A lot of people are rushing to implement them already, but they’re not production-ready yet and they’re currently scoped to Medicare patients, so coverage is limited.
There’s also a very recent ruling, like two to three weeks ago as of this recording, standardising X12 for prior auth attachments, which replaces a lot of the back-and-forth faxing that used to happen. And prior auth APIs are also coming, though that’s more of a claims workflow thing than a full patient data access path.
For now, if you’re a payer without deep EHR integration, patient-mediated exchange is probably still your easiest route.
Vendor quick reference
- TEFCA/HIE Networks for Treatment use: CommonWell Health Exchange and Carequality direct
- Value-added HIE vendors: Health Gorilla, Particle Health, Metriport (open source)
- Patient-mediated, payer-facing FHIR: Flexpa
- Patient-mediated, provider-facing: 1upHealth, Health Gorilla Patient Connect
- Manual chart chase: Datavant (absorbed Picnic Health, Seahawk, and others), ChartSquad
- HL7 v2 / integration engines: Mirth Connect (open source version still active), Rhapsody, Apache Camel, Redox
- Flat file / warehouse: Tuva Health (open source data models, good if you’re building for payer analytics or quality measures like HEDIS and eCQMs)
The vendor space is consolidating fast, a lot of these have been acquired or are in the process. It’s worth checking the current status before you commit to anything.
Here’s the complete decision tree:
If I’m missing something or got something wrong, reply and let me know. I wanted there to be a proper guide to this for 2026.
Related articles
View all
Catalonia's openEHR CDR for 8 Million People
Catalonia wanted an openEHR Clinical Data Repository for 8 million people. Medblocks worked with IBM and vitagroup to design the sync layer for hospitals.
Couchbase x Medblocks - Building a NoSQL FHIR Server
We walk you through building a FHIR server on top of Couchbase's NoSQL database, covering challenges, technical decisions, architecture, and local setup.
