> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/mobile-sdks/permissions-mapping.md).

# Permissions

The Apple Health and Health Connect types behind each HealthDataType in the 2.x SDKs, and the native permissions each 1.x CustomPermissions value requests.

This page lists what the Terra mobile SDKs ask the health store for. For 2.x, it covers requesting individual types: what each payload needs, how categories map to types, and the native types behind each one. For 1.x, see CustomPermissions in 1.x at the end of this page.

## Individual types

SDK 2.3.0 or later, on iOS, Android, React Native and Flutter. Pass `readTypes` to `permissions.request` to ask for single types instead of whole categories. The sheet then names exactly those types, and the SDK reads and uploads nothing else:

{% tabs %}
{% tab title="iOS" %}

```swift
try await terra.permissions.request(readTypes: [.steps, .heartRate, .sleepAnalysis, .weight])
```

{% endtab %}

{% tab title="Android" %}

```kotlin
terra.permissions.request(
    launcher = launcher,
    readTypes = setOf(HealthDataType.STEPS, HealthDataType.HEART_RATE, HealthDataType.SLEEP_ANALYSIS),
)
```

{% endtab %}

{% tab title="React Native" %}

```typescript
await terra.permissions.request({ readTypes: ['steps', 'heartRate', 'sleepAnalysis', 'weight'] });
```

{% endtab %}

{% tab title="Flutter" %}

```dart
await terra.permissions.request(
  readTypes: [HealthDataType.steps, HealthDataType.heartRate, HealthDataType.sleepAnalysis],
);
```

{% endtab %}
{% endtabs %}

How it behaves:

* **The install becomes type-scoped.** Once any type is requested, the SDK reads, observes and uploads only the requested types, plus the types of any category also requested whole. This holds for every later request. Types and categories join one running union, and nothing is dropped from it.
* **Empty `readTypes` keeps the category rules.** An app that never passes a type behaves exactly as before.
* **Fields are left out, not zeroed.** A route syncs only for the requested types it carries, and a payload field whose type was not requested is absent. The upload does not say which types were requested, so request every type behind the fields you use.
* **On iOS, categories you only write are not read back** once the install is type-scoped. Android never reads back a category it only writes.
* **Samsung Health is category-only.** A request with types for Samsung Health is refused before anything is recorded: natively with `IllegalArgumentException` on Android, and with `bridge.unsupported_on_platform` in React Native and Flutter.
* **Some types exist on one platform only.** The tables below mark them as iOS only or Android only. React Native and Flutter reject a type the platform has no store type for with `bridge.unsupported_on_platform`, before anything is recorded. The native SDKs have no such case: each declares only the types its store has.

Names are shared: `heartRate` in Swift, React Native and Flutter is `HealthDataType.HEART_RATE` in Kotlin.

## What each payload needs

Each table lists a payload's fields and the type to request for them.

**Daily**

| Field                            | Type                                    | Platform notes                             |
| -------------------------------- | --------------------------------------- | ------------------------------------------ |
| Steps                            | `steps`                                 |                                            |
| Active energy                    | `activeEnergy`                          |                                            |
| Basal energy                     | `basalEnergy`                           | Android reads it from basal metabolic rate |
| Distance                         | `distance`                              |                                            |
| Floors climbed                   | `floorsClimbed`                         |                                            |
| Swimming strokes                 | `swimmingStrokes`                       | iOS only                                   |
| Exercise, move and stand minutes | `exerciseTime`, `moveTime`, `standTime` | iOS only                                   |
| Heart rate                       | `heartRate`                             | Rides the daily payload, not body          |
| Resting heart rate               | `restingHeartRate`                      | Rides the daily payload, not body          |

**Activity**

| Field                                                              | Type                               | Platform notes                                                                              |
| ------------------------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------- |
| The session, its events, laps and segments, and its elevation gain | `workouts`                         | On Android, elevation gain is read under `READ_ELEVATION_GAINED`, which `workouts` asks for |
| Active energy                                                      | `activeEnergy`                     |                                                                                             |
| Distance                                                           | `distance`                         |                                                                                             |
| Steps in the session                                               | `steps`                            |                                                                                             |
| Basal energy                                                       | `basalEnergy`                      | iOS only                                                                                    |
| Swimming stroke count                                              | `swimmingStrokes`                  | iOS only                                                                                    |
| GPS route                                                          | `workoutRoute`                     | Needs `workouts`, otherwise the request fails with `workoutsRequired`                       |
| Speed, power and cycling cadence                                   | `speed`, `power`, `cyclingCadence` | Each needs `workouts`, otherwise the request fails with `workoutsRequired`                  |

**Sleep**

| Field        | Type            | Platform notes |
| ------------ | --------------- | -------------- |
| Sleep stages | `sleepAnalysis` |                |

**Body**

| Field                                                    | Type                                                                                   | Platform notes |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------- |
| Weight, height, body fat, lean mass                      | `weight`, `height`, `bodyFat`, `leanBodyMass`                                          |                |
| BMI, waist circumference, insulin, heartbeat series, ECG | `bmi`, `waistCircumference`, `insulinDelivery`, `heartbeatSeries`, `electrocardiogram` | iOS only       |
| Bone mass, body water mass                               | `boneMass`, `bodyWaterMass`                                                            | Android only   |
| Blood pressure, blood glucose, oxygen saturation         | `bloodPressure`, `bloodGlucose`, `oxygenSaturation`                                    |                |
| Body, basal and skin or wrist temperature                | `bodyTemperature`                                                                      |                |
| HRV, respiratory rate, VO2 max                           | `heartRateVariability`, `respiratoryRate`, `vo2Max`                                    |                |

**Nutrition**

| Field                   | Type                                   | Platform notes                                        |
| ----------------------- | -------------------------------------- | ----------------------------------------------------- |
| Each nutrient of a meal | The `dietary...` type of that nutrient | On Android, a meal keeps only the requested nutrients |
| Water                   | `dietaryWater`                         |                                                       |

**Menstruation**

| Field                                                                                           | Type                                                                         | Platform notes |
| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------- |
| Flow                                                                                            | `menstrualFlow`                                                              |                |
| Intermenstrual bleeding, ovulation tests, cervical mucus, sexual activity                       | `intermenstrualBleeding`, `ovulationTest`, `cervicalMucus`, `sexualActivity` |                |
| Pregnancy and progesterone tests, pregnancy, lactation, contraceptive, and cycle irregularities | The type of the same name                                                    | iOS only       |

**Athlete** (iOS only)

| Field                                                    | Type                                                                | Platform notes                                    |
| -------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------- |
| Biological sex, date of birth, wheelchair use, move mode | `biologicalSex`, `dateOfBirth`, `wheelchairUse`, `activityMoveMode` | A characteristic not requested is sent as unknown |

A field whose type was not requested is left out of the payload, not sent as zero, and nothing in the payload says it was not requested.

A type added later sends its history, as far back as a first sync reaches. A type behind a workout total, such as `distance`, sends the workouts already synced again with it.

## Move from categories to types

Each category covers the types below. To keep everything a category gave you, request all of its types. An empty `readTypes` keeps the category behaviour, and Samsung Health is requested by category only.

{% tabs %}
{% tab title="iOS" %}

| Category       | Types                                                                                                                                                                                                                                                                                                                             |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `daily`        | `steps`, `activeEnergy`, `basalEnergy`, `distance`, `swimmingStrokes`, `floorsClimbed`, `exerciseTime`, `moveTime`, `standTime`                                                                                                                                                                                                   |
| `activity`     | `steps`, `activeEnergy`, `basalEnergy`, `distance`, `swimmingStrokes`, `workouts`, `workoutRoute`, `speed`, `power`, `cyclingCadence`                                                                                                                                                                                             |
| `body`         | `heartRate`, `restingHeartRate`, `weight`, `height`, `bmi`, `bodyFat`, `leanBodyMass`, `waistCircumference`, `bloodPressure`, `bloodGlucose`, `oxygenSaturation`, `bodyTemperature`, `heartRateVariability`, `respiratoryRate`, `vo2Max`, `insulinDelivery`, `heartbeatSeries`, `electrocardiogram`                               |
| `sleep`        | `sleepAnalysis`                                                                                                                                                                                                                                                                                                                   |
| `nutrition`    | Every `dietary...` type, and `dietaryWater`                                                                                                                                                                                                                                                                                       |
| `menstruation` | `menstrualFlow`, `intermenstrualBleeding`, `ovulationTest`, `cervicalMucus`, `sexualActivity`, `pregnancyTest`, `progesteroneTest`, `pregnancy`, `lactation`, `contraceptive`, `persistentIntermenstrualBleeding`, `infrequentCycles`, `irregularCycles`, `prolongedPeriods`, `bleedingDuringPregnancy`, `bleedingAfterPregnancy` |
| `athlete`      | `biologicalSex`, `dateOfBirth`, `wheelchairUse`, `activityMoveMode`                                                                                                                                                                                                                                                               |

Heart rate and resting heart rate come with `body` on iOS. `healthObservation` and `clinicalRecord` have no types.
{% endtab %}

{% tab title="Android" %}

| Category       | Types                                                                                                                                                                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DAILY`        | `STEPS`, `ACTIVE_ENERGY`, `BASAL_ENERGY`, `DISTANCE`, `FLOORS_CLIMBED`, `HEART_RATE`, `RESTING_HEART_RATE`, `HEART_RATE_VARIABILITY`                                                                                                                |
| `ACTIVITY`     | `WORKOUTS`, `WORKOUT_ROUTE`, `SPEED`, `POWER`, `CYCLING_CADENCE`, `STEPS`, `ACTIVE_ENERGY`, `BASAL_ENERGY`, `DISTANCE`, `FLOORS_CLIMBED`, `HEART_RATE`, `HEART_RATE_VARIABILITY`                                                                    |
| `SLEEP`        | `SLEEP_ANALYSIS`, `HEART_RATE`, `RESTING_HEART_RATE`, `HEART_RATE_VARIABILITY`, `OXYGEN_SATURATION`, `RESPIRATORY_RATE`                                                                                                                             |
| `BODY`         | `WEIGHT`, `HEIGHT`, `BODY_FAT`, `LEAN_BODY_MASS`, `BONE_MASS`, `BODY_WATER_MASS`, `BLOOD_PRESSURE`, `BLOOD_GLUCOSE`, `OXYGEN_SATURATION`, `BODY_TEMPERATURE`, `HEART_RATE_VARIABILITY`, `RESPIRATORY_RATE`, `VO2_MAX`, `BASAL_ENERGY`, `HEART_RATE` |
| `NUTRITION`    | Every `DIETARY_...` type, and `DIETARY_WATER`                                                                                                                                                                                                       |
| `MENSTRUATION` | `MENSTRUAL_FLOW`, `INTERMENSTRUAL_BLEEDING`, `OVULATION_TEST`, `CERVICAL_MUCUS`, `SEXUAL_ACTIVITY`                                                                                                                                                  |

{% hint style="warning" %}
**`SLEEP` is more than sleep stages.** It also covers heart rate, resting heart rate, heart rate variability, oxygen saturation and respiratory rate. An app that replaces `SLEEP` with `SLEEP_ANALYSIS` alone stops reading them. Request all six types to keep them.
{% endhint %}
{% endtab %}
{% endtabs %}

## Native types behind each type

Some types ask for more than their name. They are marked in the tables.

{% tabs %}
{% tab title="Apple Health" %}

| Type                                                                  | HealthKit types                                                                                                                                          | Route          |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `steps`                                                               | `stepCount`                                                                                                                                              | `daily`        |
| `activeEnergy`                                                        | `activeEnergyBurned`                                                                                                                                     | `daily`        |
| `basalEnergy`                                                         | `basalEnergyBurned`                                                                                                                                      | `daily`        |
| `distance`                                                            | `distanceWalkingRunning`, `distanceCycling`, `distanceSwimming`, `distanceWheelchair`, `distanceDownhillSnowSports`, and the four distances iOS 18 added | `daily`        |
| `floorsClimbed`                                                       | `flightsClimbed`                                                                                                                                         | `daily`        |
| `swimmingStrokes`                                                     | `swimmingStrokeCount`                                                                                                                                    | `daily`        |
| `exerciseTime`                                                        | `appleExerciseTime`                                                                                                                                      | `daily`        |
| `moveTime`                                                            | `appleMoveTime`                                                                                                                                          | `daily`        |
| `standTime`                                                           | `appleStandTime`. **Also asks for** the activity summary (`activitySummaryType`), which holds stand hours                                                | `daily`        |
| `heartRate`                                                           | `heartRate`                                                                                                                                              | `daily`        |
| `restingHeartRate`                                                    | `restingHeartRate`                                                                                                                                       | `daily`        |
| `sleepAnalysis`                                                       | `sleepAnalysis`                                                                                                                                          | `sleep`        |
| `workouts`                                                            | the workout type                                                                                                                                         | `activity`     |
| `workoutRoute`                                                        | the workout route                                                                                                                                        | `activity`     |
| `speed`                                                               | `walkingSpeed`, `runningSpeed` (iOS 16+), `cyclingSpeed` (iOS 17+)                                                                                       | `activity`     |
| `power`                                                               | `runningPower` (iOS 16+), `cyclingPower` (iOS 17+)                                                                                                       | `activity`     |
| `cyclingCadence`                                                      | `cyclingCadence` (iOS 17+)                                                                                                                               | `activity`     |
| `weight`                                                              | `bodyMass`                                                                                                                                               | `body`         |
| `height`                                                              | `height`                                                                                                                                                 | `body`         |
| `bmi`                                                                 | `bodyMassIndex`                                                                                                                                          | `body`         |
| `bodyFat`                                                             | `bodyFatPercentage`                                                                                                                                      | `body`         |
| `leanBodyMass`                                                        | `leanBodyMass`                                                                                                                                           | `body`         |
| `waistCircumference`                                                  | `waistCircumference`                                                                                                                                     | `body`         |
| `bloodPressure`                                                       | `bloodPressureSystolic`, `bloodPressureDiastolic`                                                                                                        | `body`         |
| `bloodGlucose`                                                        | `bloodGlucose`                                                                                                                                           | `body`         |
| `oxygenSaturation`                                                    | `oxygenSaturation`                                                                                                                                       | `body`         |
| `bodyTemperature`                                                     | `bodyTemperature`. **Also asks for** `basalBodyTemperature` and `appleSleepingWristTemperature` (iOS 16+)                                                | `body`         |
| `heartRateVariability`                                                | `heartRateVariabilitySDNN`                                                                                                                               | `body`         |
| `respiratoryRate`                                                     | `respiratoryRate`                                                                                                                                        | `body`         |
| `vo2Max`                                                              | `vo2Max`                                                                                                                                                 | `body`         |
| `insulinDelivery`                                                     | `insulinDelivery`                                                                                                                                        | `body`         |
| `heartbeatSeries`                                                     | the heartbeat series                                                                                                                                     | `body`         |
| `electrocardiogram`                                                   | the electrocardiogram type                                                                                                                               | `body`         |
| `dietaryEnergyConsumed` to `dietaryPantothenicAcid`, one per nutrient | the `HKQuantityTypeIdentifierDietary...` type of the same name                                                                                           | `nutrition`    |
| `dietaryWater`                                                        | `dietaryWater`                                                                                                                                           | `nutrition`    |
| `menstrualFlow`                                                       | `menstrualFlow`                                                                                                                                          | `menstruation` |
| `intermenstrualBleeding`                                              | `intermenstrualBleeding`                                                                                                                                 | `menstruation` |
| `ovulationTest`                                                       | `ovulationTestResult`                                                                                                                                    | `menstruation` |
| `cervicalMucus`                                                       | `cervicalMucusQuality`                                                                                                                                   | `menstruation` |
| `sexualActivity`                                                      | `sexualActivity`                                                                                                                                         | `menstruation` |
| `pregnancyTest`                                                       | `pregnancyTestResult`                                                                                                                                    | `menstruation` |
| `progesteroneTest`                                                    | `progesteroneTestResult`                                                                                                                                 | `menstruation` |
| `pregnancy`                                                           | `pregnancy`                                                                                                                                              | `menstruation` |
| `lactation`                                                           | `lactation`                                                                                                                                              | `menstruation` |
| `contraceptive`                                                       | `contraceptive`                                                                                                                                          | `menstruation` |
| `persistentIntermenstrualBleeding`                                    | `persistentIntermenstrualBleeding` (iOS 16+)                                                                                                             | `menstruation` |
| `infrequentCycles`                                                    | `infrequentMenstrualCycles` (iOS 16+)                                                                                                                    | `menstruation` |
| `irregularCycles`                                                     | `irregularMenstrualCycles` (iOS 16+)                                                                                                                     | `menstruation` |
| `prolongedPeriods`                                                    | `prolongedMenstrualPeriods` (iOS 16+)                                                                                                                    | `menstruation` |
| `bleedingDuringPregnancy`                                             | `bleedingDuringPregnancy` (iOS 18+)                                                                                                                      | `menstruation` |
| `bleedingAfterPregnancy`                                              | `bleedingAfterPregnancy` (iOS 18+)                                                                                                                       | `menstruation` |
| `biologicalSex`                                                       | `biologicalSex`                                                                                                                                          | `athlete`      |
| `dateOfBirth`                                                         | `dateOfBirth`                                                                                                                                            | `athlete`      |
| `wheelchairUse`                                                       | `wheelchairUse`                                                                                                                                          | `athlete`      |
| `activityMoveMode`                                                    | `activityMoveMode`                                                                                                                                       | `athlete`      |

`boneMass` and `bodyWaterMass` have no HealthKit type. A type's status is `notDisclosed` wherever iOS has the type, because HealthKit never reveals a read decision.
{% endtab %}

{% tab title="Health Connect" %}
Each permission is prefixed with `android.permission.health.`.

| Type                                                                      | Permissions                                                                                                                                                                      | Route          |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `STEPS`                                                                   | `READ_STEPS`                                                                                                                                                                     | `daily`        |
| `ACTIVE_ENERGY`                                                           | `READ_ACTIVE_CALORIES_BURNED`                                                                                                                                                    | `daily`        |
| `BASAL_ENERGY`                                                            | `READ_BASAL_METABOLIC_RATE`                                                                                                                                                      | `daily`        |
| `DISTANCE`                                                                | `READ_DISTANCE`                                                                                                                                                                  | `daily`        |
| `FLOORS_CLIMBED`                                                          | `READ_FLOORS_CLIMBED`                                                                                                                                                            | `daily`        |
| `HEART_RATE`                                                              | `READ_HEART_RATE`                                                                                                                                                                | `daily`        |
| `RESTING_HEART_RATE`                                                      | `READ_RESTING_HEART_RATE`                                                                                                                                                        | `daily`        |
| `SLEEP_ANALYSIS`                                                          | `READ_SLEEP`                                                                                                                                                                     | `sleep`        |
| `WORKOUTS`                                                                | `READ_EXERCISE`. **Also asks for** `READ_ELEVATION_GAINED`, for each session's elevation gain. Its status needs `READ_EXERCISE`: `READ_ELEVATION_GAINED` alone does not grant it | `activity`     |
| `WORKOUT_ROUTE`                                                           | `READ_EXERCISE_ROUTES`, which Health Connect asks for itself, per session                                                                                                        | `activity`     |
| `SPEED`                                                                   | `READ_SPEED`                                                                                                                                                                     | `activity`     |
| `POWER`                                                                   | `READ_POWER`                                                                                                                                                                     | `activity`     |
| `CYCLING_CADENCE`                                                         | `READ_EXERCISE`                                                                                                                                                                  | `activity`     |
| `WEIGHT`                                                                  | `READ_WEIGHT`                                                                                                                                                                    | `body`         |
| `HEIGHT`                                                                  | `READ_HEIGHT`                                                                                                                                                                    | `body`         |
| `BODY_FAT`                                                                | `READ_BODY_FAT`                                                                                                                                                                  | `body`         |
| `LEAN_BODY_MASS`                                                          | `READ_LEAN_BODY_MASS`                                                                                                                                                            | `body`         |
| `BONE_MASS`                                                               | `READ_BONE_MASS`                                                                                                                                                                 | `body`         |
| `BODY_WATER_MASS`                                                         | `READ_BODY_WATER_MASS`                                                                                                                                                           | `body`         |
| `BLOOD_PRESSURE`                                                          | `READ_BLOOD_PRESSURE`                                                                                                                                                            | `body`         |
| `BLOOD_GLUCOSE`                                                           | `READ_BLOOD_GLUCOSE`                                                                                                                                                             | `body`         |
| `OXYGEN_SATURATION`                                                       | `READ_OXYGEN_SATURATION`                                                                                                                                                         | `body`         |
| `BODY_TEMPERATURE`                                                        | `READ_BODY_TEMPERATURE`, `READ_BASAL_BODY_TEMPERATURE`, `READ_SKIN_TEMPERATURE`. **Granted once any one** of the three is granted                                                | `body`         |
| `HEART_RATE_VARIABILITY`                                                  | `READ_HEART_RATE_VARIABILITY`                                                                                                                                                    | `body`         |
| `RESPIRATORY_RATE`                                                        | `READ_RESPIRATORY_RATE`                                                                                                                                                          | `body`         |
| `VO2_MAX`                                                                 | `READ_VO2_MAX`                                                                                                                                                                   | `body`         |
| `DIETARY_ENERGY_CONSUMED` to `DIETARY_PANTOTHENIC_ACID`, one per nutrient | `READ_NUTRITION`. Every nutrient shares it, because Health Connect holds a meal as one record                                                                                    | `nutrition`    |
| `DIETARY_WATER`                                                           | `READ_HYDRATION`                                                                                                                                                                 | `nutrition`    |
| `MENSTRUAL_FLOW`                                                          | `READ_MENSTRUATION`                                                                                                                                                              | `menstruation` |
| `INTERMENSTRUAL_BLEEDING`                                                 | `READ_INTERMENSTRUAL_BLEEDING`                                                                                                                                                   | `menstruation` |
| `OVULATION_TEST`                                                          | `READ_OVULATION_TEST`                                                                                                                                                            | `menstruation` |
| `CERVICAL_MUCUS`                                                          | `READ_CERVICAL_MUCUS`                                                                                                                                                            | `menstruation` |
| `SEXUAL_ACTIVITY`                                                         | `READ_SEXUAL_ACTIVITY`                                                                                                                                                           | `menstruation` |

Declare every permission behind the types you request in your manifest. A type's status is `GRANTED` once any permission behind it is granted, `DENIED` when it was asked for and none is, and `NOT_DETERMINED` when it was never asked for. A category asked for whole is still granted only when every permission behind it is.
{% endtab %}

{% tab title="Samsung Health (direct)" %}
Samsung Health is requested by category only. A request that names types for `SAMSUNG_HEALTH` is refused before anything is recorded: with `IllegalArgumentException` in the Android SDK, and with `bridge.unsupported_on_platform` in React Native and Flutter. `permissions.status(type)` answers `UNSUPPORTED`.
{% endtab %}
{% endtabs %}

## CustomPermissions in 1.x

This section covers the 1.x SDKs. In 1.x, the SDK translates Terra's `CustomPermissions` into the platform's native permissions. The tables list what each value requests on each platform.

You can request permissions in two ways:

* By data-type group: request `ACTIVITY`, `BODY`, `DAILY`, `SLEEP`, `NUTRITION` or `MENSTRUATION`. This is the default, taken from your dashboard scopes. Each group requests a broad set of native types.
* By `customPermissions`: pass a specific set of `CustomPermissions` values to request a narrower list. When `customPermissions` is non-empty, it takes precedence and the default group set is ignored.

The tables below are grouped by data domain (Activity, Heart, Vitals, and so on), with the same categories in the same order on every platform. Switch tabs to compare a value across platforms. A value marked Not supported requests no data on that platform.

{% hint style="info" %}
Permission names vary slightly between SDKs (for example, the React Native and Flutter enums use different casing and a subset of values). The mapping below uses the canonical Terra names; check your SDK's enum for the exact spelling.
{% endhint %}

{% tabs %}
{% tab title="Apple Health" %}
Each `CustomPermissions` value maps to one or more HealthKit types. When you don't pass `customPermissions`, the SDK requests every type associated with the data-type groups in your developer scopes, so the HealthKit prompt can show a long list. Pass `customPermissions` to request a narrower set.

#### Activity and workouts

| `CustomPermissions` value | HealthKit type(s) requested                                                 |
| ------------------------- | --------------------------------------------------------------------------- |
| `WORKOUT_TYPE`            | Workouts                                                                    |
| `ACTIVITY_SUMMARY`        | Activity summary, Stand time, Exercise time                                 |
| `ACTIVE_DURATIONS`        | Exercise time                                                               |
| `CALORIES`                | Active energy burned                                                        |
| `BASAL_ENERGY_BURNED`     | Resting (basal) energy burned                                               |
| `STEPS`                   | Steps                                                                       |
| `FLIGHTS_CLIMBED`         | Flights climbed                                                             |
| `EXERCISE_DISTANCE`       | Distance (walking/running, cycling, swimming, wheelchair)                   |
| `SWIMMING_SUMMARY`        | Swimming stroke count                                                       |
| `LOCATION`                | Workout route                                                               |
| `SPEED`                   | Walking speed (iOS 14+), running speed (16+), cycling speed & cadence (17+) |
| `POWER`                   | Running power (iOS 16+), cycling power (17+)                                |
| `MINDFULNESS`             | Mindful sessions                                                            |

#### Heart and cardiovascular

| `CustomPermissions` value | HealthKit type(s) requested           |
| ------------------------- | ------------------------------------- |
| `HEART_RATE`              | Heart rate                            |
| `RESTING_HEART_RATE`      | Resting heart rate                    |
| `HEART_RATE_VARIABILITY`  | Heart rate variability (SDNN)         |
| `INTERBEAT`               | Beat-to-beat measurements             |
| `ELECTROCARDIOGRAM`       | Electrocardiograms (iOS 14+)          |
| `VO2MAX`                  | VO₂ max                               |
| `BLOOD_PRESSURE`          | Blood pressure (systolic & diastolic) |

#### Vitals

| `CustomPermissions` value | HealthKit type(s) requested                       |
| ------------------------- | ------------------------------------------------- |
| `RESPIRATORY_RATE`        | Respiratory rate                                  |
| `OXYGEN_SATURATION`       | Blood oxygen                                      |
| `BLOOD_GLUCOSE`           | Blood glucose                                     |
| `BODY_TEMPERATURE`        | Body temperature (+ wrist temperature on iOS 16+) |

#### Body measurements

| `CustomPermissions` value | HealthKit type(s) requested |
| ------------------------- | --------------------------- |
| `HEIGHT`                  | Height                      |
| `WEIGHT`                  | Body mass                   |
| `BMI`                     | Body mass index             |
| `BODY_FAT`                | Body fat percentage         |
| `LEAN_BODY_MASS`          | Lean body mass              |

#### Sleep

| `CustomPermissions` value | HealthKit type(s) requested |
| ------------------------- | --------------------------- |
| `SLEEP_ANALYSIS`          | Sleep analysis              |

#### Nutrition

| `CustomPermissions` value | HealthKit type(s) requested |
| ------------------------- | --------------------------- |
| `NUTRITION_CALORIES`      | Dietary energy consumed     |
| `NUTRITION_PROTEIN`       | Dietary protein             |
| `NUTRITION_CARBOHYDRATES` | Dietary carbohydrates       |
| `NUTRITION_FAT_TOTAL`     | Dietary total fat           |
| `NUTRITION_FIBRE`         | Dietary fiber               |
| `NUTRITION_SUGAR`         | Dietary sugar               |
| `NUTRITION_SODIUM`        | Dietary sodium              |
| `NUTRITION_CHOLESTEROL`   | Dietary cholesterol         |
| `NUTRITION_VITAMIN_C`     | Dietary vitamin C           |
| `NUTRITION_VITAMIN_A`     | Dietary vitamin A           |
| `NUTRITION_WATER`         | Dietary water               |

#### Reproductive health

| `CustomPermissions` value | HealthKit type(s) requested |
| ------------------------- | --------------------------- |
| `MENSTRUATION`            | Menstrual flow              |

#### Profile

| `CustomPermissions` value | HealthKit type(s) requested |
| ------------------------- | --------------------------- |
| `GENDER`                  | Biological sex              |
| `DATE_OF_BIRTH`           | Date of birth               |

#### Symptoms

| `CustomPermissions` value | HealthKit type(s) requested |
| ------------------------- | --------------------------- |
| `SYMPTOM_COUGHING`        | Coughing (iOS 13.6+)        |
| `SYMPTOM_FEVER`           | Fever (iOS 13.6+)           |
| `SYMPTOM_SORE_THROAT`     | Sore throat (iOS 13.6+)     |

{% hint style="info" %}
Requesting a data-type group (rather than `customPermissions`) requests a broad superset of types. For example, the Body group requests heart rate, HRV, VO₂ max, glucose, blood pressure, body temperature, ECG and more, not just body-composition metrics. Use `customPermissions` when you want the HealthKit prompt to show only specific toggles.
{% endhint %}
{% endtab %}

{% tab title="Health Connect" %}
On Android, the `HEALTH_CONNECT`, `SAMSUNG` and `GOOGLE_FIT` connections all read through Health Connect and request the same Health Connect permissions. They differ only in which data they return:

* `HEALTH_CONNECT` returns data from all apps that write to Health Connect.
* `SAMSUNG` returns only data written by the Samsung Health app.
* `GOOGLE_FIT` returns only data written by the Google Fit app.

So the permission prompt a user sees is identical across the three; the filtering happens when Terra reads the data.

A value marked Not supported requests no data on Health Connect, even if you pass it.

#### Activity and workouts

| `CustomPermissions` value | Health Connect record(s) requested                          |
| ------------------------- | ----------------------------------------------------------- |
| `WORKOUT_TYPE`            | Exercise session                                            |
| `ACTIVITY_SUMMARY`        | Exercise session, Active calories, Total calories, Distance |
| `ACTIVE_DURATIONS`        | Exercise session                                            |
| `CALORIES`                | Active calories, Total calories                             |
| `BASAL_ENERGY_BURNED`     | Basal metabolic rate                                        |
| `STEPS`                   | Steps                                                       |
| `FLIGHTS_CLIMBED`         | Floors climbed                                              |
| `EXERCISE_DISTANCE`       | Distance                                                    |
| `SWIMMING_SUMMARY`        | Not supported                                               |
| `LOCATION`                | Not supported                                               |
| `SPEED`                   | Speed                                                       |
| `POWER`                   | Power                                                       |
| `MINDFULNESS`             | Exercise session                                            |

#### Heart and cardiovascular

| `CustomPermissions` value | Health Connect record(s) requested |
| ------------------------- | ---------------------------------- |
| `HEART_RATE`              | Heart rate                         |
| `RESTING_HEART_RATE`      | Resting heart rate, Heart rate     |
| `HEART_RATE_VARIABILITY`  | Heart rate variability (RMSSD)     |
| `INTERBEAT`               | Not supported                      |
| `ELECTROCARDIOGRAM`       | Not supported                      |
| `VO2MAX`                  | VO₂ max                            |
| `BLOOD_PRESSURE`          | Blood pressure                     |

#### Vitals

| `CustomPermissions` value | Health Connect record(s) requested |
| ------------------------- | ---------------------------------- |
| `RESPIRATORY_RATE`        | Respiratory rate                   |
| `OXYGEN_SATURATION`       | Oxygen saturation                  |
| `BLOOD_GLUCOSE`           | Blood glucose                      |
| `BODY_TEMPERATURE`        | Body temperature                   |

#### Body measurements

| `CustomPermissions` value | Health Connect record(s) requested |
| ------------------------- | ---------------------------------- |
| `HEIGHT`                  | Height                             |
| `WEIGHT`                  | Weight                             |
| `BMI`                     | Weight, Height                     |
| `BODY_FAT`                | Body fat                           |
| `LEAN_BODY_MASS`          | Lean body mass                     |

#### Sleep

| `CustomPermissions` value | Health Connect record(s) requested |
| ------------------------- | ---------------------------------- |
| `SLEEP_ANALYSIS`          | Sleep session                      |

#### Nutrition

| `CustomPermissions` value                      | Health Connect record(s) requested |
| ---------------------------------------------- | ---------------------------------- |
| `NUTRITION_*` (all macro/micronutrient values) | Nutrition                          |
| `NUTRITION_WATER`                              | Hydration                          |

#### Reproductive health

| `CustomPermissions` value | Health Connect record(s) requested                       |
| ------------------------- | -------------------------------------------------------- |
| `MENSTRUATION`            | Menstruation flow (+ Menstruation period on Android 14+) |

#### Profile

| `CustomPermissions` value | Health Connect record(s) requested |
| ------------------------- | ---------------------------------- |
| `GENDER`                  | Not supported                      |
| `DATE_OF_BIRTH`           | Not supported                      |
| {% endtab %}              |                                    |

{% tab title="Samsung Health (direct)" %}
{% hint style="info" %}
This applies only to the Samsung-specific SDK builds that integrate the Samsung Health SDK directly. On the standard SDK, the `SAMSUNG` connection reads Samsung Health data through Health Connect. See the Health Connect mapping. If you are not on a Samsung-tagged build, use that table.
{% endhint %}

On Samsung-tagged builds, the `SAMSUNG` connection requests Samsung Health data types directly (read access only). A value marked Not supported requests no data.

#### Activity and workouts

| `CustomPermissions` value | Samsung Health data type(s) requested |
| ------------------------- | ------------------------------------- |
| `WORKOUT_TYPE`            | Activity summary, Exercise            |
| `ACTIVITY_SUMMARY`        | Activity summary, Exercise            |
| `ACTIVE_DURATIONS`        | Activity summary, Exercise            |
| `CALORIES`                | Activity summary, Exercise            |
| `BASAL_ENERGY_BURNED`     | Not supported                         |
| `STEPS`                   | Steps                                 |
| `FLIGHTS_CLIMBED`         | Floors climbed                        |
| `EXERCISE_DISTANCE`       | Activity summary, Exercise            |
| `SWIMMING_SUMMARY`        | Activity summary, Exercise            |
| `LOCATION`                | Exercise location                     |
| `SPEED`                   | Not supported                         |
| `POWER`                   | Not supported                         |
| `MINDFULNESS`             | Activity summary, Exercise            |

#### Heart and cardiovascular

| `CustomPermissions` value | Samsung Health data type(s) requested |
| ------------------------- | ------------------------------------- |
| `HEART_RATE`              | Heart rate                            |
| `RESTING_HEART_RATE`      | Heart rate                            |
| `HEART_RATE_VARIABILITY`  | Not supported                         |
| `INTERBEAT`               | Not supported                         |
| `ELECTROCARDIOGRAM`       | Not supported                         |
| `VO2MAX`                  | Not supported                         |
| `BLOOD_PRESSURE`          | Blood pressure                        |

#### Vitals

| `CustomPermissions` value | Samsung Health data type(s) requested |
| ------------------------- | ------------------------------------- |
| `RESPIRATORY_RATE`        | Sleep                                 |
| `OXYGEN_SATURATION`       | Blood oxygen                          |
| `BLOOD_GLUCOSE`           | Blood glucose                         |
| `BODY_TEMPERATURE`        | Body temperature                      |

#### Body measurements

| `CustomPermissions` value | Samsung Health data type(s) requested |
| ------------------------- | ------------------------------------- |
| `HEIGHT`                  | Body composition                      |
| `WEIGHT`                  | Body composition                      |
| `BMI`                     | Body composition                      |
| `BODY_FAT`                | Body composition                      |
| `LEAN_BODY_MASS`          | Body composition                      |

#### Sleep

| `CustomPermissions` value | Samsung Health data type(s) requested |
| ------------------------- | ------------------------------------- |
| `SLEEP_ANALYSIS`          | Sleep                                 |

#### Nutrition

| `CustomPermissions` value                      | Samsung Health data type(s) requested |
| ---------------------------------------------- | ------------------------------------- |
| `NUTRITION_*` (all macro/micronutrient values) | Nutrition                             |
| `NUTRITION_WATER`                              | Water intake                          |

#### Reproductive health

| `CustomPermissions` value | Samsung Health data type(s) requested |
| ------------------------- | ------------------------------------- |
| `MENSTRUATION`            | Not supported                         |

#### Profile

| `CustomPermissions` value | Samsung Health data type(s) requested |
| ------------------------- | ------------------------------------- |
| `GENDER`                  | User profile                          |
| `DATE_OF_BIRTH`           | User profile                          |

{% hint style="info" %}
Several metrics that are not supported on the Samsung direct integration (`HEART_RATE_VARIABILITY`, `VO2MAX`, `SPEED`, `POWER`, `BASAL_ENERGY_BURNED`, `MENSTRUATION`) are available when reading Samsung data via Health Connect, so the Health Connect path offers wider coverage for those metrics.
{% endhint %}
{% endtab %}
{% endtabs %}
