FHIR chart export API

Use FHIR chart export endpoints to retrieve patient, encounter, note, assessment, and directory resources as FHIR JSON.

Authentication

Send x-api-key with export scope for patient-specific exports.

/publicFhirDirectory is public directory data and does not require patient chart access.

Endpoints

• GET /exportFhirPatient exports patient demographics and coverage.
• GET /exportFhirPatientBundle exports a longitudinal patient bundle.
• GET /exportFhirEncounter exports an encounter.
• GET /exportFhirNote exports a note as Composition and DocumentReference resources.
• GET /exportFhirAssessment exports assessment data.
• GET /publicFhirDirectory exports public Organization, Practitioner, and Location records.

Common query parameters

• patientId is required for patient-specific exports.
• Use encounterId, noteId, or assessmentId for object-specific exports.
• Use limit parameters to keep longitudinal bundles bounded.

Patient export example

curl -X GET "https://popularishealth.web.app/exportFhirPatient?patientId=patient_12345" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/fhir+json"

Longitudinal bundle example

curl -X GET "https://popularishealth.web.app/exportFhirPatientBundle?patientId=patient_12345&encounterLimit=5&noteLimit=5&assessmentLimit=3&medicalHistoryLimit=50" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/fhir+json"

Encounter export example

curl -X GET "https://popularishealth.web.app/exportFhirEncounter?patientId=patient_12345&encounterId=encounter_100" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/fhir+json"

Encounter exports include linked diagnosis, procedure, and visit context when available.

Note export example

curl -X GET "https://popularishealth.web.app/exportFhirNote?patientId=patient_12345&noteId=note_100" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/fhir+json"

Note exports include FHIR Composition and DocumentReference resources.

Assessment export example

curl -X GET "https://popularishealth.web.app/exportFhirAssessment?patientId=patient_12345&assessmentId=assessment_100" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/fhir+json"

Assessment exports include Questionnaire-style resources when available.

Public directory example

curl -X GET "https://popularishealth.web.app/publicFhirDirectory?resourceType=Organization&limit=25" \
  -H "Accept: application/fhir+json"

Response headers

• x-request-id is returned for tracing and can be supplied by the caller.
• x-ratelimit-limit shows the request limit for the current key.
• x-ratelimit-remaining shows requests left in the current window.
• x-ratelimit-reset shows when the current rate-limit window resets.

Response shape

FHIR export responses return standard FHIR JSON resources such as Patient, Encounter, Composition, or Bundle.

{
  "resourceType": "Bundle",
  "id": "fhir-patient-bundle-patient-12345",
  "type": "collection",
  "timestamp": "2026-03-07T13:45:00.000Z",
  "total": 4,
  "entry": [
    {
      "fullUrl": "Patient/patient-patient-12345",
      "resource": {
        "resourceType": "Patient",
        "id": "patient-patient-12345"
      }
    }
  ]
}

When to use FHIR vs HL7

Use FHIR when the partner can consume resource-based JSON. Use HL7 export when the partner expects HL7 v2 messages.

Common errors

• 401: the API key is missing, revoked, or invalid.
• 403: the key does not include FHIR export scope.
• 404: the requested patient, encounter, note, assessment, or export object was not found.
• 429: the partner key exceeded its configured rate limit.

For inbound FHIR payloads, review the FHIR intake guide.