Epic's FHIR R4 API enables access to electronic health record (EHR) data including patients, encounters, observations, conditions, medications, and more. Epic supports SMART on FHIR and OAuth 2.0 for authorization. The open sandbox at fhir.epic.com allows testing with synthetic data. Production access requires registration with Epic's App Orchard and approval from individual health systems.
pip install requestsVerified import paths — ran on the pinned version, not inferred.
Fetch a test patient resource from the Epic FHIR R4 open sandbox using a Bearer token.
Implement a SMART on FHIR authorization flow or backend service JWT-based token exchange before making API calls.
Register your app at appmarket.epic.com and obtain endpoint URLs from each organization's FHIR metadata endpoint.
Always set headers={'Accept': 'application/fhir+json'} on every request.Implement token refresh using the refresh_token grant or re-authenticate via the backend JWT flow before expiry.
Check for bundle.get('link') entries with relation 'next' and follow them until no next link is returned.Request only the SMART scopes you need (e.g. patient/Patient.read, patient/Observation.read) and verify they are granted in the token response.
Avoid running pip as the 'root' user by utilizing a Python virtual environment. To resolve the update notification, run: `pip install --upgrade pip`.
Ensure your JWT is correctly signed (RS384 algorithm) and has not expired. Verify the `client_id` is correct for the environment (sandbox vs. production). If using backend services, ensure your public key is uploaded and synced with Epic (which can take hours). For token requests, confirm `Content-Type: application/x-www-form-urlencoded` and data in the request body, not the querystring.
Review your application's configuration in Epic's App Orchard or `fhir.epic.com` to ensure all required API endpoints and corresponding scopes (e.g., `patient.read`, `Observation.read`) are enabled for your app. Remember that changes to app configurations can take time to sync to the sandbox environment.
Verify that your FHIR server base URL is accurate (e.g., `https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4` for R4 in sandbox). Ensure the `aud` parameter in your authorization request matches the correct FHIR endpoint for the version you are targeting. For resource-specific lookups, use valid test patient or resource IDs available in the Epic sandbox documentation.
After creating your developer app and uploading your public key, you *must* wait some time (potentially several hours or even a day) for the credentials to become active and sync across Epic's systems. Double-check that you are using the correct `client_id` for the sandbox or production environment and that your JWT is properly formed and signed (RS384).
This usually requires contacting Epic support (open@epic.com or Vendor Services) as it's an issue with the sandbox user account itself, not your application's code. Occasionally, these accounts may be unblocked automatically after a period, or Epic might reset them.