> For the complete documentation index, see [llms.txt](https://docs.thryve.health/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thryve.health/thryve-data-sources/apple-health.md).
# Apple Health
With Thryve you can easily integrate your iOS application with Apple Health, Apple's on-device health data store, via the \`ThryveAppleHealth\` module.
`ThryveAppleHealth` handles the HealthKit permission flow so your app can easily read health data (steps, vitals, sleep, workouts, nutrition, and more) recorded by the iPhone, Apple Watch, and any other app or device that writes to Apple Health, without having to integrate each source separately.
{% hint style="warning" %}
Apple Health is only available on iOS. Your app must have the **HealthKit** capability with **Background Delivery** enabled, and both `NSHealthShareUsageDescription` and `NSHealthUpdateUsageDescription` in its `Info.plist`. A missing description leads to rejection during App Store review. See [Setup Thryve SDK → iOS](/integrate-your-mobile-app/setup-thryve-sdk/ios.md) for the full project configuration.
{% endhint %}
{% hint style="info" %}
On devices without HealthKit (e.g. iPads before iPadOS 17), `start` returns error `70004` and Apple Health is not shown in the Thryve Connection Widget.
{% endhint %}
#### Data availability
Apple Health only exposes data that has already been written to it on the user's iPhone, by the iPhone itself, a paired Apple Watch, or a third-party app (e.g. a scale, a sleep tracker, a nutrition app). If nothing writes a given data type to Apple Health, Thryve will not receive it either.
* **First sync is today only.** The first `synchronize` after connecting (or after `stop`, reinstall, or a new device) fetches data for the current day only. Use [historic data backfill](/integrate-your-mobile-app/apple-health-health-connect-and-samsung-health.md#historic-data-backfill) to fetch earlier data.
* **Backfill limits.** `backfillEpoch` accepts ranges of up to 30 days and `backfillDaily` up to 365 days per call. Longer ranges return error `70015`; split them into several calls.
* **Limited history (iOS 27 and later).** After choosing data types, the user picks how much history to share: **Past 30 Days and Future Data** or **All Recorded Data and Future Data**. With the 30-day option, Apple Health never returns data recorded before that limit, in backfill or in `synchronize`, and without an error. New data keeps syncing, but backfill of older data returns nothing, and data that another app or device writes to Apple Health late, dated before the limit, is skipped.
* **Denied permissions are invisible.** For privacy reasons, iOS never tells an app whether the user denied read access to a data type. A denied type behaves exactly like a type with no data: it syncs successfully and returns nothing.
* **Data is locked with the phone.** Apple Health data is encrypted while the iPhone is locked. A sync that runs while the device is locked cannot read data and fails with error `70106`. The data is picked up by the next sync after the user unlocks the phone.
* **Background timing is controlled by iOS.** The SDK asks HealthKit to wake the app as soon as new data arrives, but iOS decides when that actually happens based on battery, device usage and system load. We recommend calling `synchronize` whenever your app comes to the foreground.
* **Permissions are per device.** HealthKit permissions do not move to a new iPhone. If the user is connected on the Thryve backend but has granted no permissions on the current device, the SDK returns error `70031`. Call `start` again to show the permission sheet.
{% hint style="info" %}
We recommend asking users to choose **All Recorded Data and Future Data** on the iOS 27 permission screen, for example in your onboarding before calling `start`. Apps cannot preselect this option, and iOS only tells an app when access is limited, never when full access was granted.
{% endhint %}
{% hint style="warning" %}
Calling `stop` stops data synchronization, but your app will still appear as connected in the Apple Health app. Apple does not allow apps to revoke their own access. Only the user can remove it in **Health → Profile → Apps**.
{% endhint %}
#### Capabilities
* **Lifecycle & permissions:** Connects and disconnects via `start` / `stop`, checks availability and active state, and requests HealthKit read permissions for the data types you configure.
* **Incremental sync:** `synchronize` uses HealthKit anchored queries to fetch only new and updated samples since the last sync, plus daily aggregates, and uploads them to the Thryve backend.
* **Background sync:** Uses HealthKit background delivery to sync when new data is written to Apple Health, even while your app is in the background. Enabled by default via `enableBackgroundSync` in `ThryveAppleHealthConfig`.
* **Historical backfill:** `backfillEpoch` reads raw samples over a date range (up to 30 days); `backfillDaily` reads daily aggregates over a date range (up to 365 days).
* **Data types & configuration:** Maps over 90 HealthKit data types into Thryve's standardised format. You choose which types to request in `ThryveAppleHealthConfig.dataTypes`.
* **Observability:** OpenTelemetry-style spans for sync, backfill, permission requests, reads and uploads to aid debugging and monitoring. See [Observability](/integrate-your-mobile-app/observability.md).
#### Supported Data Types
The `ThryveAppleHealth` module supports over 90 HealthKit data types, including quantity types (e.g. steps, heart rate, body mass), category types (e.g. sleep analysis, mindful sessions), workouts, heartbeat series, ECG and characteristics (e.g. date of birth, biological sex). We map these to Thryve's standard data types. See the [full list](https://airtable.com/appUsNn6CVszlBjfw/shroLjZ7pigt4oV7j/tblUI4OiE28Soe8DR) of supported data types.
#### How to integrate Thryve SDK Apple Health module
1. Configure your Xcode project for HealthKit: Setup [Thryve SDK → iOS](/integrate-your-mobile-app/setup-thryve-sdk/ios.md). For React Native and Flutter, see [React Native](/integrate-your-mobile-app/setup-thryve-sdk/react-native.md) and [Flutter](/integrate-your-mobile-app/setup-thryve-sdk/flutter.md).
2. Add `ThryveAppleHealthConfig` to your SDK configuration and connect the user: [Connect data sources.](/integrate-your-mobile-app/connect-data-sources.md)
3. Set up background, manual and historic synchronization: [Apple Health, Health Connect & Samsung Health.](/integrate-your-mobile-app/apple-health-health-connect-and-samsung-health.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.thryve.health/thryve-data-sources/apple-health.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
