Bulk FHIR export, from kickoff to CSV.

A system-level export ($export on the server) takes everything. A patient-level export (Patient/$export) takes every patient. A FHIR group export (Group/{id}/$export) takes the members of one Group, and that is the export the certification criterion requires and the one a study needs. Clinical Extract runs the Group export and adds _type to request only the resource types the study reads, so the request covers only the cohort and its variables.

The kickoff is one GET with Prefer: respond-async and Accept: application/fhir+json. The server answers 202 Accepted at once, with a Content-Location header naming the status URL. Clinical Extract polls that URL; while the export runs the server answers 202 with Retry-After (and, on Epic, X-Progress), and Clinical Extract waits the interval Retry-After specifies. When the export is done the status URL answers 200 with the manifest: transactionTime (the time the data is as of), request (the kickoff URL), requiresAccessToken, output (one entry per NDJSON file: its type, its URL, its line count) and error (OperationOutcome files). Each file is fetched with Accept: application/fhir+ndjson and the bearer token, and the status URL is deleted once the files are safe in your study folder.

Each line of an NDJSON file is one complete FHIR resource. Clinical Extract joins it to its patient's row by subject.reference, uses the LOINC code (or the RxNorm, ICD-10-CM or SNOMED CT code) to pick the column, writes the coded value into the cell, and records where the column came from in data-dictionary.json: the description with its code system, the FHIR element, an example. The result is study.csv, with a row for each patient in the cohort and a column for each approved variable, and every column described. The steps between the token and the file are on the how-it-works page.

Jones et al. (JAMIA, 2024) measured (g)(10) bulk export at five sites. Epic sites ran at 502 to 2,827 resources per minute, and Cerner above 8,000 per minute; it took the sites 2 to 119 days (mean 65) from submitting cohort criteria to the first successful bulk request. At those rates, export time grows with the number of resources requested: a 212-patient study cohort exports in under three hours at Epic's slowest reported rate and in minutes at Cerner's, while a whole population takes weeks. Clinical Extract therefore exports only the study Group, and the cohort builder fixes the cohort and its count before the first request. Source: Jones et al. J Am Med Inform Assoc. 2024, doi:10.1093/jamia/ocae040.

Each EHR page shows the registration, the activation and the export in that vendor's own vocabulary, with a dated fact table and the specimens: Epic, Oracle Health, eClinicalWorks, athenahealth, MEDITECH, NextGen and Veradigm EHR. How each one exposes the API is the hub. For eClinicalWorks, the $export exchange request by request is in our developer guide for eClinicalWorks.