---
title: "Clinical Records API: Reading FHIR Health Records in HealthKit"
canonical: "https://aifitnessapi.com/data/clinical-records-api"
cluster: "Health Data"
primary_query: "healthkit clinical records api"
last_reviewed: "2026-10-04"
description: "Read FHIR health records with HKClinicalRecord: the nine clinical types, DSTU2 and R4, the health-records entitlement, usage key, and SMART Health Cards."
publisher: "AIFitnessAPI — independent, not sponsored"
cite_as: "\"Clinical Records API: Reading FHIR Health Records in HealthKit\", AIFitnessAPI, https://aifitnessapi.com/data/clinical-records-api"
---

# Clinical Records API: Reading FHIR Health Records in HealthKit

> Apple HealthKit exposes health records that people download from supported healthcare institutions as read-only HKClinicalRecord samples, each wrapping one FHIR resource as an HKFHIRResource whose JSON you parse yourself. Apple documents nine clinical type identifiers, from allergyRecord to coverageRecord, and two FHIR releases, DSTU2 and R4. Access needs the Clinical Health Records capability (the health-records value of the com.apple.developer.healthkit.access entitlement) and the NSHealthClinicalHealthRecordsShareUsageDescription key, and Apple warns that App Review may reject apps that enable the capability without using the data. SMART Health Cards and EU Digital COVID Certificates arrive separately as HKVerifiableClinicalRecord, through a query that needs its own entitlement.

- Canonical: https://aifitnessapi.com/data/clinical-records-api
- Last reviewed: 2026-10-04
- Publisher: AIFitnessAPI (https://aifitnessapi.com) — independent, not sponsored
- Cite as: "Clinical Records API: Reading FHIR Health Records in HealthKit", AIFitnessAPI, https://aifitnessapi.com/data/clinical-records-api

---

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](https://developer.apple.com/documentation/healthkit/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."

| Symbol | Platforms in Apple's reference | What it gives you |
| --- | --- | --- |
| `HKClinicalRecord` | iOS 12.0, iPadOS 12.0, Mac Catalyst 13.0, macOS 13.0, visionOS 1.0 | `clinicalType`, `displayName`, `fhirResource` |
| `HKFHIRResource` | iOS 12.0, iPadOS 12.0, Mac Catalyst 13.0, macOS 13.0, visionOS 1.0 | `identifier` (the FHIR `id`), `resourceType`, `sourceURL`, `data` (the JSON), `fhirVersion` (iOS 14.0) |
| `HKFHIRVersion` | iOS 14.0, iPadOS 14.0, Mac Catalyst 14.0, macOS 13.0, visionOS 1.0 | `primaryDSTU2()`, `primaryR4()`, `fhirRelease`, version numbers |
| `HKFHIRRelease` | Not stated on the page | `dstu2`, `r4`, `unknown` |
| `HKClinicalTypeIdentifier` | iOS 12.0, iPadOS 12.0, Mac Catalyst 13.0, macOS 13.0, visionOS 1.0, watchOS 5.0 | Nine identifiers, below |
| `HKVerifiableClinicalRecord` | iOS 15.0, iPadOS 15.0, Mac Catalyst 15.0, macOS 13.0, visionOS 1.0 | SMART Health Card or EU Digital COVID Certificate contents |
| `HKCDADocumentSample` | Listed under Apple's medical records topic | "A Clinical Document Architecture (CDA) sample that stores a single document." |

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:

| Identifier | Apple's description | iOS |
| --- | --- | --- |
| `allergyRecord` | "records of allergic or intolerant reactions" | 12.0 |
| `conditionRecord` | "records of a condition, problem, diagnosis, or other event" | 12.0 |
| `immunizationRecord` | "records of the current or historical administration of vaccines" | 12.0 |
| `labResultRecord` | "records of lab results" | 12.0 |
| `medicationRecord` | "records of medication" | 12.0 |
| `procedureRecord` | "records of procedures" | 12.0 |
| `vitalSignRecord` | "records of vital signs" | 12.0 |
| `coverageRecord` | "records containing information about the user's insurance coverage" | 14.0 |
| `clinicalNoteRecord` | "records of clinical notes" | 16.4 |

`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](/fix/healthkit-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

| Source | What it gives you | Verified from |
| --- | --- | --- |
| Apple HealthKit | Read-only FHIR resources as `HKClinicalRecord`; signed cards as `HKVerifiableClinicalRecord` | Apple HealthKit reference and articles, fetched 2026-10-04 |
| Android Health Connect | FHIR R4 and R4B resources as `MedicalResource`, behind experimental APIs | See [Health Connect medical records API](/data/health-connect-medical-records-api) |
| Spike | Its pitch spans wearables, IoT, lab systems and electronic medical records | Described on our [Terra vs Spike comparison](/compare/terra-vs-spike); verify specifics in Spike's docs |
| Other wearable cloud APIs and aggregators | Not documented on our pages, so verify with each vendor | None |

## 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](/compliance/app-store-guideline-5-1-3-health-research) page quotes that section in full, and [App Store health-data rules](/compliance/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](/compliance/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.

## FAQ

### Which clinical record types can a HealthKit app request?

Apple's HKClinicalTypeIdentifier lists nine: allergyRecord, conditionRecord, immunizationRecord, labResultRecord, medicationRecord, procedureRecord and vitalSignRecord from iOS 12.0, coverageRecord from iOS 14.0, and clinicalNoteRecord from iOS 16.4. All are read-only. Apple states that you cannot request authorization to share clinical record types and cannot create or save new HKClinicalRecord objects, so request them in the read set only.

[Permalink](https://aifitnessapi.com/data/clinical-records-api#faq-1)

### Which FHIR versions does HealthKit return for health records?

HKFHIRVersion, available from iOS 14.0, offers primaryDSTU2() and primaryR4(), and HKFHIRRelease has the cases dstu2, r4 and unknown. Each HKFHIRResource reports its own fhirVersion, so one person's store can hold both releases. Apple's Accessing Health Records article still points readers to the DSTU2 1.0.2 specification and the Argonaut Data Query guide, so write a parser per release and branch on the version.

[Permalink](https://aifitnessapi.com/data/clinical-records-api#faq-2)

### Why do HealthKit clinical record dates not match the visit date?

Apple documents that HKClinicalRecord inherits startDate and endDate from HKSample but does not fill them from the FHIR data. They reflect when the system downloaded the FHIR data to the device. Sorting or filtering by those dates gives you download order, not clinical order. Read the dates from the resource JSON in fhirResource.data, using the field that resource type defines.

[Permalink](https://aifitnessapi.com/data/clinical-records-api#faq-3)

### Do I need permission to read SMART Health Cards in HealthKit?

Not in the usual way. Apple documents that HKVerifiableClinicalRecordQueryDescriptor does not need prior authorization, because HealthKit prompts the user each time the underlying query runs. It does need a special entitlement from Apple; without it the query fails with HKError.Code.errorAuthorizationDenied. Results are HKVerifiableClinicalRecord samples whose signed payload, from dataRepresentation, you can verify against the issuer's public key.

[Permalink](https://aifitnessapi.com/data/clinical-records-api#faq-4)