In short
- Bulk FHIR is the HL7 Bulk Data Access standard: you start an asynchronous $export for the whole system, all patients or one group, poll a status URL, and download one NDJSON file per resource type.
- Clients authenticate with SMART Backend Services, a client credentials grant signed with a one-time JWT, and tokens are short-lived with no refresh tokens.
- EHRs certified under ONC's §170.315(g)(10) must support group export, and CMS lists the Bulk Data guide among the standards for payer APIs due January 1, 2027, so bulk access is becoming a normal integration path.
Bulk FHIR export is how you pull data for a whole population from an EHR or payer system without making one API call per patient. Under the HL7 Bulk Data Access implementation guide, your backend service sends one $export request for the whole system, for all patients, or for a defined group. The server prepares the data in the background, you poll a status URL, and you then download newline-delimited JSON (NDJSON) files, one resource type per file. Authorization uses SMART Backend Services, with no user in the loop.
This guide is for engineering leads building analytics, population health, quality reporting or research data feeds.
When do you need Bulk FHIR instead of regular FHIR APIs?
The guide was written for organizations accountable for managing the health of populations. Its authors note that large exports can require hundreds of thousands of requests if you use the regular single-resource APIs. Bulk export replaces that with one asynchronous job. The guide lists these use cases:
- Exporting the resources behind the US Core Data for Interoperability (USCDI) profiles from an EHR.
- Exporting a common financial data set, such as Patient, ExplanationOfBenefit, Coverage and Claim, from financial systems.
- Terminology data (CodeSystem and ValueSet) and provider data (Practitioner, Location, Organization).
- Public health surveillance and electronic case reporting.
If your app works one patient at a time, for example a clinician opening a chart, regular FHIR reads are the right tool. If you need a nightly or weekly copy of data for thousands of patients, bulk export is.
What are the three export levels?
- System: [fhir base]/$export. Everything the server holds that the client app is allowed to see.
- Patient: [fhir base]/Patient/$export. Data for all patients, or, with a POST and the patient parameter, for a listed set of patients.
- Group: [fhir base]/Group/[id]/$export. Data for the members of one defined group, such as a panel, a program cohort or an attributed population.
Group export is the one you are most likely to meet in practice, because ONC certification requires it. The health system defines the group. Your job is to agree with it which group you may export.
How does the export flow work?
The guide defines four steps: kick-off, status polling, completion and file download.
1. Kick-off
GET [base]/Group/[id]/$export?_type=Patient,Observation&_since=2026-11-01T00:00:00Z
Accept: application/fhir+json
Prefer: respond-async
-> 202 Accepted, Content-Location: [status URL]
2. Poll
GET [status URL]
-> 202 Accepted (X-Progress, Retry-After) while running
-> 429 Too Many Requests if you poll too often
3. Complete
-> 200 OK, Expires header, JSON body:
transactionTime, request, requiresAccessToken, output[], error[], deleted[]
4. Download
GET each output[].url (with a bearer token if requiresAccessToken is true)
-> NDJSON, one resource type per file
Cancel at any time: DELETE [status URL]A few details from the spec shape the client code. The kick-off should send Accept: application/fhir+json and Prefer: respond-async, the only values the guide supports. While the job runs, the server returns 202 with an optional X-Progress header and should send Retry-After. Clients should use exponential backoff. A server may also return 429 with Retry-After to refuse a new export while one is already running. When the job finishes, the server should return an Expires header saying when the files will stop being available. The completed response always includes an error array, so check it on every run.
Which parameters matter?
- _outputFormat: defaults to application/fhir+ndjson. Servers must support NDJSON.
- _since: only resources changed after this time. Servers must support it, and it is the key to incremental loads.
- _type: limit the export to the resource types you name. Optional for servers, and when supported, the simplest way to keep exports small.
- patient: a list of patients to restrict the export to. POST only.
- _elements, includeAssociatedData and _typeFilter: optional and marked experimental in the guide. _typeFilter applies FHIR search criteria per type, but search result parameters such as _include and _sort must not be used.
Use _type every time. Asking only for the resource types you need is faster for the server and supports the HIPAA minimum necessary principle on your side. Then use the transactionTime from each completed export as the _since value for the next one, so each run picks up only what changed.
How do you authenticate a bulk client?
Bulk export runs with no user present, so it uses SMART Backend Services. The spec says the client must be a confidential client that can protect its credential, registered with the server in advance with its public key. For each token request, the client signs a one-time-use JWT and posts it with grant_type=client_credentials. Scopes use the system/ context, for example system/Observation.rs.
Tokens are deliberately short-lived. The spec says access tokens issued under this profile shall be short-lived, that expires_in should not exceed 300 seconds, and that refresh tokens should not be issued. Long exports therefore outlive their first token. Request a fresh token before each poll and each download. All exchanges with the token endpoint require TLS 1.2 or later.
What do certified EHRs have to support?
ONC's §170.315(g)(10) criterion requires certified Health IT Modules to respond to requests for multiple patients' data as a group. The standard is Bulk Data Access v1.0.0 STU 1, including mandatory support for the group-export operation, with v1.0.1 required for testing and v2.0.0 STU 2 approved as an alternative version. Authorization for system scopes must follow the SMART Backend Services guide, although modules may use other access control schemes such as capability URLs.
The data follows USCDI and US Core: the base standards are USCDI v3 and US Core 6.1.0, with newer versions approved through ONC's Standards Version Advancement Process. In practice this means an EHR certified for (g)(10) gives you a group export of US Core data. Anything beyond that, such as custom groups, extra resource types or experimental parameters, varies by vendor.
What does Bulk FHIR look like on a real EHR?
Oracle Health's Millennium documentation is a useful example of how a vendor fills in the spec:
- Group export is based on Bulk Data v1.0.1 with several experimental parameters from v2.0.0. Patient export is based on v2.0.0.
- Patient export does not support exporting all patients. You must provide a list of patient IDs.
- You register a Bulk Data SMART application in code Console, and open (unauthenticated) endpoints do not support bulk export.
- Developers work with the health system to identify the available groups, which organizations manage in Ignite Management Tooling.
- Bulk jobs run against the organization's database and share services with other applications, so export time depends on population size, the number of resource types, the time range and concurrent load.
- With the header Prefer: handling=lenient, unknown or unsupported parameters are ignored instead of causing an error.
Expect each vendor to differ in the same places: which levels it supports, how groups are created, which parameters it honors and how it throttles. Read the vendor's bulk documentation before you design the schedule.
Does Bulk FHIR apply to health plans?
Increasingly, yes. CMS's Interoperability and Prior Authorization final rule (CMS-0057-F) lists FHIR Bulk Data Access v1.0.0 STU 1 among its required standards and points to the rule's own table for which standard applies to which API. The rule requires Medicare Advantage organizations, state Medicaid and CHIP fee-for-service programs, Medicaid and CHIP managed care plans, and QHP issuers on the federal exchanges to implement a Provider Access API by January 1, 2027.
That API shares claims and encounter data, USCDI data and certain prior authorization information with in-network providers who have a treatment relationship with the patient. Payers must keep an attribution process that links patients to those providers and must let patients opt out. Group export fits that kind of attributed provider panel.
How should you design the pipeline?
- Schedule exports when the source system is quiet, and agree the schedule with the health system's IT team, since bulk jobs share its database.
- Run incremental exports with _since set to the previous transactionTime, and a full export only when you must rebuild.
- Download files promptly. They expire, and the Expires header tells you when.
- Land the raw NDJSON first, unchanged, then transform. If a mapping bug appears later you can reprocess without another export.
- Make loads idempotent. Upsert by resource type and ID so a retried file does not create duplicates.
- Process the deleted array when the server provides it, so records removed at the source do not live on in your warehouse.
- Read the error array on every run and alert on it. A job can complete with partial errors.
- Encrypt the files at rest and in transit, limit who can read the landing area, and delete raw files on a schedule you can explain.
A bulk feed usually ends in an analytics store. Plan the patient matching, terminology mapping and data quality checks for that store at the same time as the export client, because that is where most of the work sits.
We have shipped Epic and athenahealth integrations, and for any vendor platform we work from the vendor's documentation and sandbox. We sign a BAA before anyone on our team sees PHI. If you are planning a population data feed, talk to one of our engineers. Our free five-day technical audit ends with a written report on your export design, authorization setup and downstream data model.
Sources
- HL7 FHIR Bulk Data Access (Flat FHIR) IG, STU 2: overview
- HL7 FHIR Bulk Data Access IG, STU 2: Export
- HL7 SMART App Launch: Backend Services
- ASTP/ONC: §170.315(g)(10) Standardized API for patient and population services
- Oracle: Bulk Data Access for Millennium
- CMS fact sheet: Interoperability and Prior Authorization final rule (CMS-0057-F)