Technical requirements and specifications for Health Records

FHIR version R4-supported EHR systems for Health Records

FHIR version DSTU2-supported EHR systems for Health Records

Support for FHIR version R4

Health Records supports FHIR version R4 (v4.0.1) and follows the US Core Implementation Guide v3.1.1. It’s recommended that newly registering organizations use FHIR version R4 if available.

For organizations already registered for Health Records using FHIR version DSTU2, you may be able to upgrade to FHIR version 4.

Apple Business Register automatically detects whether FHIR version R4 or FHIR version DSTU2 is used by an organization or its EHR vendor, and Apple Business Register runs the relevant tests for FHIR API validation.

HL7 FHIR implementation requirements

• Your FHIR API must be configured to your EHR vendor’s specification as follows:

  • If conforming to FHIR version R4: US Core Implementation Guide v3.1.1

  • If conforming to FHIR version DSTU2: Argonaut Data Query Implementation Guide Version 1.0.0

• Your FHIR API endpoint must be publicly available.

• Your organization must support SMART on FHIR OAuth and provide your patients with user name and password credentials for authenticating their identities against your FHIR API endpoints.

Required FHIR resources

The following FHIR resources are required to the same degree that they’re available from your patient portal:

• AllergyIntolerance

• Condition

• Clinical Notes

  • Binary

  • DocumentReference

  • DiagnosticReport

• Immunization

• MedicationRequest (applies only to FHIR version R4 APIs)

• Observation (only for the labs and vital signs categories)

• Patient

• Procedure

Test patient account requirements

A test patient account in your production environment can be made available to Apple for as long as your organization supports Health Records. The account must consist exclusively of fictitious data. Using this fictitious account, Apple’s test systems monitor connectivity to your FHIR API endpoint. They also alert you and Apple to any issues found.

When Apple detects errors with the test patient account during routine monitoring, Apple notifies your administrative and technical contacts.

• High severity errors: If certain errors—such as those affecting the authorization certificate, authorization server, token server, or all FHIR resources—aren’t resolved within 24 hours, Apple temporarily disables your FHIR API endpoint. This prevents your patients from encountering issues while trying to connect to your organization from the Health app. To reenable the FHIR API endpoint, you must resolve these errors.

• Medium severity errors: When Apple detects errors related to one or more (but not all) FHIR resources, Apple notifies you of any errors impacting patients. Your organization should fix these errors quickly.

The test patient data should include at least one entry for each of the FHIR resources listed above. To ensure that your test patient account is implemented properly and will pass Apple’s routine monitoring of your FHIR API endpoint, consult with your EHR vendor.

The following data are required for the test patient account:

• Patient Portal Enabled

• Test-Patient Portal User Name

• Test-Patient Portal Password

• Allergy: Minimum of one allergy documented with an associated RxNorm or NDF-RT code for the allergen

• Condition: Minimum of one problem documented with an associated SNOMED diagnosis code for problem or diagnosis

• Clinical Notes: Minimum of one clinical note (for example, progress notes, consult notes, or a scan of a lab report)

• Immunization: Minimum of one immunization documented with an associated CVX code

• MedicationRequest: Minimum of one medicationRequest documented on the outpatient medication list with an associated RxNorm code for medication (applies only to FHIR version R4 APIs)

• Lab Order Result: Minimum of one lab result with associated LOINC codes

  Note: To make sure your patients have access to their COVID-19 test results and have the results display correctly in the Health app, add COVID-19 antigen (Viral test) and COVID-19 antibody (Serology test) results under the lab results (FHIR resource Observation) category. For supported LOINC codes, see the Guidance for mapping to SARS-CoV-2 LOINC terms website.

• Vital Signs: Minimum of one vital sign measurement documented with associated LOINC codes

• Procedure: Minimum of one procedure documented with an associated CPT or SNOMED code for documented procedure

• Patient: Expose Patient resource with at least name and birthdate

If Cerner is your EHR vendor, run the Cerner Smart App Validator and confirm that all resources pass. If Epic is your EHR vendor, run the Epic API Configuration Checker and confirm that all resources pass.

Refresh token requirements

Health Records supports two refresh token methods. Of the two methods, Apple highly recommends the first one.

• Renewable refresh token requirements (recommended): After successful authorization, the Health app should receive an access token, which should be valid for at least 10 minutes, and a refresh token, which should be valid for at least 3 months.

  Whenever the refresh token is used while valid, the token’s lifetime must be extended 3 months into the future or a new refresh token valid for at least 3 months must be issued. The renewable refresh token will prevent your patients from having to enter a user name and password each time a request is made to download data from your FHIR API endpoint. See the ONC’s Cures Act Final Rule for more details on this requirement. Consult with your EHR vendor to ensure that your refresh tokens are configured according to Apple’s specifications.

• Long-lived refresh token requirements: Your refresh token must be valid for at least a year from when it was first granted. The long-lived refresh token will prevent your patients from having to enter a user name and password each time a request is made to download data from your FHIR API endpoint. Consult with your EHR vendor to ensure that your refresh tokens are configured according to Apple’s specifications.