Apple HealthKitV2 Clinical Records Export Format

Updated March 22, 2024 19:00

Clinical Records in HealthKit have a unique data structure for capturing information specific to the participant. Use HealthKit’s clinical record support to read Fast Healthcare Interoperability Resources (FHIR) from supported healthcare institutions. Instead of focusing on documents, FHIR breaks the user’s medical history into discrete records. HealthKit then represents each FHIR record as a sample. Please refer to Apple's HealthKit FHIR Resource Type article for a complete list of HealthKit clinical record samples.

One file will be created per type of data (e.g., "ClinicalAllergy" and "ClinicalImmunization"). The file name will correspond to the type of data (e.g., "HealthKitV2ClinicalRecords_ClinicalAllergy_20211101-20211217" and "HealthKitV2ClinicalRecords_ClinicalImmunization_20211101-20211217").

Data Fields
Sample CSV Export
Sample JSON Export

Data Fields

Field	Description
`HealthKitClinicalRecordKey`	A unique, auto-generated key for this clinical record.
`ParticipantIdentifier`	The identifier of the participant this task was for. Can be used to cross reference with Participants.
`ParticipantID`	The stable, automatically generated, internal system identifier for this participant. Universally unique identifier (UUID).
`Date`	Sync date of the clinical record, in ISO 8601 format. Includes timezone offset information.
`DisplayName`	The primary display name as shown in the Health app.
`ResourceSourceUrl`	The full URL for the source of the FHIR resource.
`ResourceData`	The JSON representation of the FHIR resource.
`ResourceIdentifier`	The value from the FHIR resource’s resourceIdentifier field.
`ResourceType`	The value from the FHIR resource’s resourceType field.
`SourceIdentifier`	A unique identifier for the source object.
`SourceName`	The name of the source app which generated the reading. In the case of a “`com.apple.health.*`” `SourceIdentifier`, this is the name of the Apple Device used to generate the reading (e.g. “Chris’ iPhone”).
`SourceVersion`	The version of the source app which generated the reading. In the case of a “`com.apple.health.*`” `SourceIdentifier`, this is the version of iOS or WatchOS on the device used to generate the reading.
`SourceOperatingSystemVersion`	An arbitrary string representing the version of the software running on the device, if applicable.
`SourceProductType`	An arbitrary string representing the hardware version of the device, if applicable.
`Metadata`	Additional XML metadata inserted by the source application.
`InsertedDate`	The creation date of the entry, in ISO 8601 format. Is always in UTC.

If a participant re-syncs their device, you may observe duplicate samples. HealthKit samples are immutable, so when doing data analysis, your team will need to remove any samples that have the same HealthKitClinicalRecordKey and ParticipantIdentifier as another sample.

Sample CSV Export

HealthKitClinicalRecordKey,ParticipantIdentifier,Date,DisplayName,ResourceSourceUrl,ResourceData,ResourceIdentifier,ResourceType,SourceIdentifier,SourceName,SourceVersion,SourceOperatingSystemVersion,SourceProductType,Metadata,InsertedDate
b8f73772-341c-55ae-b870-ff67e36cda14,256263d8-3ffc-eb11-aaae-0afb9334277d,2021-12-14T12:21:03-05:00,CO2,https://sample.org,"{""status"":""final"",""category"":{""text"":""Laboratory"",""coding"":[{""system"":""http://hl7.org/fhir/observation-category"",""display"":""Laboratory"",""code"":""laboratory""}]},""issued"":""2021-09-23T19:19:40Z"",""id"":""SampleID"",""code"":{""text"":""CO2"",""coding"":[{""system"":""http://loinc.org"",""display"":""Carbon dioxide, total [Moles/volume] in Serum or Plasma"",""code"":""2028-9""}]},""valueQuantity"":{""code"":""mmol/L"",""value"":29,""system"":""http://unitsofmeasure.org"",""unit"":""mmol/L""},""subject"":{""display"":""McSample, Sample"",""reference"":""https://sample.org""},""performer"":[{""display"":""M Willis"",""reference"":""https://sample.org/""}],""effectiveDateTime"":""2021-09-23T19:19:00Z"",""referenceRange"":[{""low"":{""code"":""mmol/L"",""value"":22,""system"":""http://unitsofmeasure.org"",""unit"":""mmol/L""},""high"":{""code"":""mmol/L"",""value"":30,""system"":""http://unitsofmeasure.org"",""unit"":""mmol/L""},""text"":""22 - 30 mmol/L""}],""resourceType"":""Observation""}",SampleID1,Observation,com.apple.public.health.clinical.A5C6F309-3570-E7CB-9876-749D6875A153,Hospital,15.1,15.1.0,"iPhone11,8",null,2021-12-14T21:06:42Z
9be22c10-1e2a-53e6-a1d2-1504cc4dde86,256263d8-3ffc-eb11-aaae-0afb9334277d,2021-12-14T12:21:03-05:00,HEMOGLOBIN,https://sample.org,"{""status"":""final"",""category"":{""text"":""Laboratory"",""coding"":[{""system"":""http://hl7.org/fhir/observation-category"",""display"":""Laboratory"",""code"":""laboratory""}]},""issued"":""2021-09-23T19:19:40Z"",""id"":""SampleID"",""code"":{""text"":""HEMOGLOBIN"",""coding"":[{""system"":""http://loinc.org"",""display"":""Hemoglobin [Mass/volume] in Blood"",""code"":""718-7""}]},""valueQuantity"":{""code"":""g/dL"",""value"":15.9,""system"":""http://unitsofmeasure.org"",""unit"":""g/dL""},""subject"":{""display"":""McSample, Sample"",""reference"":""https://sample.org/""},""performer"":[{""display"":""M Willis"",""reference"":""https://sample.org/""}],""effectiveDateTime"":""2021-09-23T19:19:00Z"",""referenceRange"":[{""low"":{""code"":""g/dL"",""value"":14,""system"":""http://unitsofmeasure.org"",""unit"":""g/dL""},""high"":{""code"":""g/dL"",""value"":17.4,""system"":""http://unitsofmeasure.org"",""unit"":""g/dL""},""text"":""14.0 - 17.4 g/dL""}],""resourceType"":""Observation""}",SampleID2,Observation,com.apple.public.health.clinical.A5C6F309-3570-E7CB-9876-749D6875A153,Hospital,15.1,15.1.0,"iPhone11,8",null,2021-12-14T21:06:42Z
23710292-0f29-5802-a183-83e496877b84,256263d8-3ffc-eb11-aaae-0afb9334277d,2021-12-14T12:21:03-05:00,ALBUMIN,https://sample.org,"{""status"":""final"",""category"":{""text"":""Laboratory"",""coding"":[{""system"":""http://hl7.org/fhir/observation-category"",""display"":""Laboratory"",""code"":""laboratory""}]},""issued"":""2021-09-23T19:19:40Z"",""id"":""SampleID"",""code"":{""text"":""ALBUMIN"",""coding"":[{""system"":""http://loinc.org"",""display"":""Albumin [Mass/volume] in Serum or Plasma"",""code"":""1751-7""}]},""valueQuantity"":{""code"":""g/dL"",""value"":4.7,""system"":""http://unitsofmeasure.org"",""unit"":""g/dL""},""subject"":{""display"":""McSample, Sample"",""reference"":""https://sample.org/""},""performer"":[{""display"":""M Willis"",""reference"":""https://sample.org/""}],""effectiveDateTime"":""2021-09-23T19:19:00Z"",""referenceRange"":[{""low"":{""code"":""g/dL"",""value"":3.5,""system"":""http://unitsofmeasure.org"",""unit"":""g/dL""},""high"":{""code"":""g/dL"",""value"":5.2,""system"":""http://unitsofmeasure.org"",""unit"":""g/dL""},""text"":""3.5 - 5.2 g/dL""}],""resourceType"":""Observation""}",SampleID3,Observation,com.apple.public.health.clinical.A5C6F309-3570-E7CB-9876-749D6875A153,Hospital,15.1,15.1.0,"iPhone11,8",null,2021-12-14T21:06:42Z

Sample JSON Export

{
 "HealthKitClinicalRecordKey":"b8f73772-341c-55ae-b870-ff67e36cda14",
 "ParticipantIdentifier":"256263d8-3ffc-eb11-aaae-0afb9334277d",
 "Date":"2021-12-14T12:21:03-05:00",
 "DisplayName":"CO2",
 "Resource":
  {
   "SourceUrl":"https://sample.org/",
   "Data":
    {
     "status":"final",
     "category":
      {
       "text":"Laboratory",
       "coding":
        [
         {
          "system":"http://hl7.org/fhir/observation-category",
          "display":"Laboratory","code":"laboratory"
         }
        ]
      },
     "issued":"2021-09-23T19:19:40Z",
     "id":"SampleID",
     "code":
      {
       "text":"CO2",
       "coding":
        [
         {
          "system":"http://loinc.org",
          "display":"Carbon dioxide, total [Moles/volume] in Serum or Plasma",
          "code":"2028-9"
         }
        ]
      },
     "valueQuantity":
      {
       "code":"mmol/L",
       "value":29,
       "system":"http://unitsofmeasure.org",
       "unit":"mmol/L"
      },
     "subject":
      {
       "display":"McSample, Sample",
       "reference":"https://sample.org/"
      },
     "performer":
      [
       {
        "display":"M Willis",
        "reference":"https://sample.org/"
       }
      ],
     "effectiveDateTime":"2021-09-23T19:19:00Z","referenceRange":
      [
       {
        "low":
         {
          "code":"mmol/L",
          "value":22,"system":"http://unitsofmeasure.org",
          "unit":"mmol/L"
         },
        "high":
        {
         "code":"mmol/L",
         "value":30,
         "system":"http://unitsofmeasure.org",
         "unit":"mmol/L"
        },
       "text":"22 - 30 mmol/L"
      }
     ],
    "resourceType":"Observation"
   },
  "Identifier":"SampleID",
  "Type":"Observation"
 },
 "Source":
  {
   "Name":"Hospital",
   "Identifier":"com.apple.public.health.clinical.ID",
   "Version":"15.1","OperatingSystemVersion":"15.1.0",
   "ProductType":"iPhone11,8"
  },
 "Metadata":null,
 "InsertedDate":"2021-12-14T21:06:42Z"
}

Was this article helpful?

Apple HealthKitV2 Clinical Records Export Format

Table of Contents

Data Fields

Sample CSV Export

Sample JSON Export