Bulk data export

PrevHealth supports FHIR Bulk Data Access for a configured patient group using the Group/{id}/$export operation. System-level and patient-level $export are not supported.

Requirements

A registered backend-services client (see Authorization).
The scope system/*.read.
The id of the group your client may export. It is provided when your client is registered. The export contains only that group's patients and the practitioners, organizations and locations their records refer to.

A job can be polled, downloaded and cancelled only by the client (and subject) that started it.

1. Kick off

GET https://clinic.prevhealth.us/fhir/r4/Group/<group id>/$export?_type=Patient,Condition&_since=2026-01-01T00:00:00Z HTTP/1.1
Authorization: Bearer <access token>
Accept: application/fhir+json
Prefer: respond-async

Parameter	Required	Meaning
`Prefer: respond-async` header	Recommended	The only supported preference; any other `Prefer` value is rejected with 400.
`_type`	No	Comma-separated resource types. Default: all supported types. Supported: Patient, AllergyIntolerance, CarePlan, CareTeam, Condition, Coverage, Device, DocumentReference, Goal, Immunization, MedicationDispense, MedicationRequest, Observation, Procedure, RelatedPerson, DiagnosticReport, ServiceRequest, Encounter, Specimen, Medication, Organization, Practitioner, PractitionerRole, Location, Provenance, QuestionnaireResponse.
`_since`	No	A FHIR instant with a time zone, e.g. `2026-01-01T00:00:00Z`. Resources last updated at or before this instant are excluded. Resources without an update time are included.
`_outputFormat`	No	`application/fhir+ndjson` (default), `application/ndjson` or `ndjson`.

Response: 202 Accepted with a Content-Location header holding the status URL and an empty body.

2. Poll the status URL

GET https://clinic.prevhealth.us/fhir/r4/bulk-export/status/<job id>
Authorization: Bearer <access token>

202 while the job runs, with a Retry-After header (seconds). Wait that long before polling again.
200 when complete. The body is a JSON manifest:

{
  "transactionTime": "2026-11-02T10:00:00Z",
  "request": "https://clinic.prevhealth.us/fhir/r4/Group/<id>/$export?...",
  "requiresAccessToken": true,
  "output": [{ "type": "Patient", "url": "https://clinic.prevhealth.us/fhir/r4/bulk-export/file/<job id>/Patient" }],
  "error": [{ "type": "OperationOutcome", "url": "https://clinic.prevhealth.us/fhir/r4/bulk-export/error/<job id>" }]
}

A job that failed still returns 200; its error array points at an OperationOutcome file (bulk-export/error/<job id>) describing the failure.

3. Download

GET https://clinic.prevhealth.us/fhir/r4/bulk-export/file/<job id>/<ResourceType>
Authorization: Bearer <access token>
Accept: application/fhir+ndjson

Each file is newline-delimited JSON, one resource per line. Request bulk-export/error/<job id> for the OperationOutcome describing a failed export; it returns 404 when the job produced no errors.

4. Cancel

DELETE the status URL. The server answers 202 Accepted; later requests for that job return 404.

Errors

Status	Cause
400	`_since` is not a valid FHIR instant with a time zone, `_type` names an unsupported type, `_outputFormat` is not one of the NDJSON values above, or `Prefer` is not `respond-async`.
401	Missing, invalid, expired or revoked access token.
403	The token lacks `system/*.read`.
404	Unknown group, or the group has no members; an unknown or cancelled job; or a job started by a different client (reported as not found so job ids cannot be probed).

The body of an error is a FHIR OperationOutcome. See Errors and exceptions.