Clinical Records API: Reading FHIR Health Records in HealthKit

Clinical records are the one HealthKit category your app can never write. A person connects an account at a supported healthcare institution in the Health app, the system downloads their records in FHIR, and, in Apple's words, "updates the records in the background on a regular basis." Your app reads what arrived.

What Apple ships#

Apple's Accessing Health Records article explains the model: "Instead of focusing on documents, FHIR breaks the user's medical history into discrete records. HealthKit then represents each FHIR record as an HKClinicalRecord sample that stores a single condition, procedure, or result."

Note that Apple's HKClinicalRecord page lists no watchOS version, although HKClinicalTypeIdentifier lists watchOS 5.0. Read records on iPhone or iPad.

The nine clinical type identifiers, with the first version Apple lists for iOS:

HKFHIRResourceType lists twelve FHIR resource types: allergyIntolerance, condition, diagnosticReport, documentReference, immunization, medicationOrder, medicationDispense, medicationStatement, medicationRequest, observation, procedure and coverage.

Setup: capability, entitlement, usage key#

Apple's setup guidance is direct: "Only select the Clinical Health Records checkbox if your app needs to access the user's clinical records. App Review may reject apps that enable the Clinical Health Records capability if the app doesn't actually use the health record data."

• Entitlement. The checkbox adds health-records to com.apple.developer.healthkit.access, the HealthKit Capabilities Entitlement. Apple's value description: "The app can request access to FHIR-backed clinical records." Apple adds: "Only add values for data types that your app needs to access."
• Usage string. NSHealthClinicalHealthRecordsShareUsageDescription is "A message to the user that explains why the app requested permission to read clinical records," and Apple marks it: "This key is required if your app uses APIs that access the user's clinical records." Its page lists iOS 12.0, iPadOS 12.0 and visionOS 1.0. You still need NSHealthShareUsageDescription as for any HealthKit read.
• Privacy policy. Apple notes that apps reading clinical records "must have a valid Privacy Policy URL in the app store submission," and that the URL "appears as a link on the clinical record permission sheet."
• Device check. supportsHealthRecords() "returns true if the device is set to a locale where clinical records are supported, or if the user already has clinical records downloaded to their HealthKit store." Call it before you show a health-records feature.

Authorization#

Request clinical types in the read set and pass nil to share. Apple: "clinical records are read-only, so you can't request authorization to share clinical record types. You can't create or save new HKClinicalRecord objects." You can mix clinical and ordinary types in one call, but "HealthKit presents the clinical record types in a separate permission sheet to ensure the user understands exactly what they're approving."

An app that cannot work without records can declare them in NSHealthRequiredReadAuthorizationTypeIdentifiers. Apple requires "three or more required clinical record types." If the user denies any of them, authorization fails with HKError.Code.errorRequiredAuthorizationDenied, and "Your app is not told the record types to which the user denied access." Our required authorization denied page covers that failure.

Reading and parsing#

Each query returns one clinical type. Apple documents two predicates. predicateForClinicalRecords(withFHIRResourceType:) narrows to one FHIR resource type. predicateForClinicalRecords(from:fhirResourceType:identifier:) finds a specific resource, with a warning worth repeating: "the system only guarantees that the FHIR identifier is unique for a particular resource type from a given source. To identify a record uniquely, you must check the identifier, type, and source."

The rest is FHIR. Apple's resource object exposes a few attributes, but the clinical content is in data, which you decode as JSON. Apple's own advice: "to access this data you need to understand the FHIR specification."

Traps#

• Dates mean download time. Apple: "the system does not populate these properties with information from the FHIR data; instead, the startDate and endDate reflect the time and date when the system downloaded the FHIR data to the device." Never sort a timeline by sample dates.
• Types and resources do not map one to one. Apple splits FHIR Observation "into the labResultRecord and vitalSignRecord identifiers," so you query them separately. In the other direction, medicationRecord "matches medicationStatement, medicationOrder, medicationRequest, and medicationDispense types," so one query returns a mixture unless you add the resource-type predicate.
• Two FHIR releases. Records carry DSTU2 or R4, and HKFHIRRelease also has unknown. Apple's article still links "FHIR specification (DSTU2, 1.0.2)" and the Argonaut Data Query guide. Branch on fhirVersion before parsing.
• Clinical notes have files. For clinicalNoteRecord, Apple says notes "can have one or more attached files," often PDF, HTML or text but "they can be any format." Check each HKAttachment contentType. Read permission on the type covers the attachments.
• Not every person has records. Records exist only where the person connected a supported institution. Design the empty state first.

SMART Health Cards and COVID certificates#

Verifiable records are a separate path. Apple describes HKVerifiableClinicalRecord samples as data "from a SMART Health Card or EU Digital COVID Certificate" that "combine information about the user's identity with clinical data, like an immunization record or a lab test result," cryptographically signed by the issuing organization. Apple lists the verification steps: read dataRepresentation, unzip it, parse the iss value naming the issuer, fetch the issuer's public key, and verify the signature. jwsRepresentation is marked deprecated.

You read them with HKVerifiableClinicalRecordQueryDescriptor (iOS 15.4), filtering by credential type (covid19, immunization, laboratory, recovery) and source type (smartHealthCard, euDigitalCOVIDCertificate). Apple documents two differences from every other query. "Unlike other HealthKit queries, you don't need to request permission to read verifiable health records before using this descriptor. HealthKit prompts the user for permission to read the records each time your app runs the underlying query." And: "Running an HKVerifiableClinicalRecordQuery requires a special entitlement from Apple, or the query fails with an HKError.Code.errorAuthorizationDenied error."

Other sources#

Review rules and privacy#

Apple's article warns that "App Review may reject apps that don't use clinical record data appropriately" and points to the Health and Health Research section of the App Store Review Guidelines. Our guideline 5.1.3 page quotes that section in full, and App Store health-data rules collects the others. Clinical records may also bring you closer to regulated health data, depending on who you are and who you work with; see is fitness data PHI. This page describes APIs. It is not legal or medical advice, and your app should not interpret a person's records for them.

Before you ship#

Enable the capability only if you read records. Write the usage string for a real person. Branch on FHIR release, read clinical dates from the JSON, and identify records by identifier, type and source together. If you want SMART Health Cards, apply for the verifiable-records entitlement before you build the feature.