> 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/health-and-fitness-api/sdk-references/react-native.md).

# React Native

## Connections

| Value                        | Platform | Description                                                               |
| ---------------------------- | -------- | ------------------------------------------------------------------------- |
| `Connections.APPLE_HEALTH`   | iOS      | Apple Health (HealthKit)                                                  |
| `Connections.SAMSUNG`        | Android  | Samsung Health, read via Health Connect (filtered to Samsung Health data) |
| `Connections.HEALTH_CONNECT` | Android  | Health Connect (reads all data sources)                                   |
| `Connections.GOOGLE`         | Android  | Google Fit (via Health Connect, filtered to Google Fit data)              |

## CustomPermissions

Use these to request a subset of permissions. When not specified, all permissions from your developer scopes are requested. See the [CustomPermissions enum](https://github.com/tryterra/terra-react/blob/master/src/enums/CustomPermissions.ts) for the exact value names. The tables below show what each value requests on each platform; see [Permissions mapping](/reference/health-and-fitness-api/sdk-references/permissions-mapping.md) for the full reference.

{% 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 & 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 & 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 dash (—) means the value is **not supported** on Health Connect and requests no data, even if you pass it.

## Activity & 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`        | —                                                           |
| `LOCATION`                | —                                                           |
| `SPEED`                   | Speed                                                       |
| `POWER`                   | Power                                                       |
| `MINDFULNESS`             | Exercise session                                            |

## Heart & 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`               | —                                  |
| `ELECTROCARDIOGRAM`       | —                                  |
| `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`                  | —                                  |
| `DATE_OF_BIRTH`           | —                                  |
| {% 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 dash (—) means the value is **not supported** and requests no data.

## Activity & 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`     | —                                     |
| `STEPS`                   | Steps                                 |
| `FLIGHTS_CLIMBED`         | Floors climbed                        |
| `EXERCISE_DISTANCE`       | Activity summary, Exercise            |
| `SWIMMING_SUMMARY`        | Activity summary, Exercise            |
| `LOCATION`                | Exercise location                     |
| `SPEED`                   | —                                     |
| `POWER`                   | —                                     |
| `MINDFULNESS`             | Activity summary, Exercise            |

## Heart & cardiovascular

| `CustomPermissions` value | Samsung Health data type(s) requested |
| ------------------------- | ------------------------------------- |
| `HEART_RATE`              | Heart rate                            |
| `RESTING_HEART_RATE`      | Heart rate                            |
| `HEART_RATE_VARIABILITY`  | —                                     |
| `INTERBEAT`               | —                                     |
| `ELECTROCARDIOGRAM`       | —                                     |
| `VO2MAX`                  | —                                     |
| `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`            | —                                     |

## 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 %}

## Types

### SuccessMessage

```typescript
type SuccessMessage = {
  success: boolean;
  error: string | null;
};
```

### DataMessage

```typescript
type DataMessage = {
  success: boolean;
  data: Object;
  error: string | null;
};
```

When `toWebhook` is `true`, the `data` field contains `{ reference: string }` — a reference ID for the webhook payload. When `false`, `data` contains the full normalized health data object.

### GetUserId

```typescript
type GetUserId = {
  success: boolean;
  userId: string | null;
};
```

## **Initialization**

### initTerra

Creates and authenticates a Terra SDK instance. This **makes a network call** to Terra's servers to validate your developer ID and reconnect existing users.

```typescript
function initTerra(
  devID: string,
  referenceId: string | null,
): Promise<SuccessMessage>
```

* `devID: string` ➡ Your developer ID from the [Terra Dashboard](https://dashboard.tryterra.co).
* `referenceId: string | null` ➡ An identifier for your app's user. This value appears as `reference_id` in webhook payloads and API responses, allowing you to map Terra users back to your own user system.

**returns** `Promise<SuccessMessage>`

{% hint style="warning" %}
You must `await` this call and verify `success` is `true` before calling any other SDK function.
{% endhint %}

## **Connection setup/management**

### **initConnection**

Authenticates a new user connection with Terra's servers and triggers the platform permission dialog (HealthKit on iOS, Health Connect on Android). This **makes a network call**.

This function should only be called **once** per user/connection type. On subsequent app launches, `initTerra` will automatically reconnect existing users.

```typescript
function initConnection(
  connection: Connections,
  token: string,
  schedulerOn: boolean,
  customPermissions: CustomPermissions[] = []
): Promise<SuccessMessage>
```

* `connection: Connections` ➡ The connection type (e.g. `Connections.APPLE_HEALTH`, `Connections.SAMSUNG`, `Connections.HEALTH_CONNECT`). Must match the platform — passing an iOS connection on Android (or vice versa) will fail.
* `token: string` ➡ A **single-use** authentication token from the [Generate Authentication Token](https://docs.tryterra.co/reference/generate-authentication-token) endpoint.
* `schedulerOn: boolean` ➡ Enables automatic data delivery. On **iOS**, enables HealthKit background delivery (also requires `setUpBackgroundDelivery` in AppDelegate). On **Android**, enables periodic WorkManager-based data fetches (activity every 20min, other types every 8hrs).
* (Optional) `customPermissions: CustomPermissions[]` ➡ Request specific permissions. Empty array defaults to all scopes.

**returns** `Promise<SuccessMessage>` — check `error` field for specific failure reasons (invalid token, user limit reached, etc.)

### checkAuth

Checks whether a connection is authenticated by **making a network call** to Terra's servers.

```typescript
function checkAuth(
  connection: Connections,
  devID: string
): Promise<Pick<SuccessMessage, 'success'>>
```

* `connection: Connections` ➡ The connection type to check.
* `devID: string` ➡ Your developer ID.

**returns** `Promise<{ success: boolean }>`

### getUserId

Returns the Terra user ID for a connection. This is a local read with no network call.

The returned `userId` is the same identifier used in webhook payloads, API requests, and the Terra dashboard.

```typescript
function getUserId(connection: Connections): Promise<GetUserId>
```

* `connection: Connections` ➡ The connection to get the user ID for.

**returns** `Promise<GetUserId>` — `userId` is `null` if no connection exists for this type.

## Data retrieval

All data retrieval functions **make network calls** — even with `toWebhook = false`, the SDK sends data to Terra's normalization servers and returns the normalized result.

{% hint style="info" %}
**`toWebhook` behavior:**

Both paths require network connectivity.
{% endhint %}

| `toWebhook`      | What happens                                      | `DataMessage.data` contains                   |
| ---------------- | ------------------------------------------------- | --------------------------------------------- |
| `true` (default) | Data is fetched and sent to your webhook          | `{ reference: string }` — a reference ID only |
| `false`          | Data is fetched, normalized, and returned locally | The full normalized health data object        |

### **getActivity**

Retrieves workout and exercise session data.

```typescript
function getActivity(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: boolean = true
): Promise<DataMessage>
```

### **getDaily**

Retrieves daily summary data (steps, calories, distance, heart rate, etc.).

```typescript
function getDaily(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: boolean = true
): Promise<DataMessage>
```

### **getBody**

Retrieves body measurement data (weight, height, BMI, heart rate, blood pressure, etc.).

```typescript
function getBody(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  latestReading: boolean = false,
  toWebhook: boolean = true
): Promise<DataMessage>
```

* `latestReading: boolean` ➡ When `true`, returns only the most recent reading for each body metric, ignoring the date range. Defaults to `false`. **Note: this parameter only takes effect on iOS.** On Android, it is accepted but not forwarded to the native SDK.

### getSleep

Retrieves sleep session data (stages, duration, heart rate during sleep, etc.).

```typescript
function getSleep(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: boolean = true
): Promise<DataMessage>
```

### **getNutrition**

Retrieves nutrition and meal data.

```typescript
function getNutrition(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: boolean = true
): Promise<DataMessage>
```

### getMenstruation

Retrieves menstrual cycle data. **iOS only** — rejects with an error on Android.

```typescript
function getMenstruation(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: boolean = true
): Promise<DataMessage>
```

### getAthlete

Retrieves the user's athlete profile (biographical data, no date range needed). **iOS only** — rejects with an error on Android.

{% hint style="warning" %}
Unlike other data getters, `getAthlete` does not parse the native response. The `data` field may contain a raw JSON string rather than a parsed object.
{% endhint %}

```typescript
function getAthlete(
  connection: Connections,
  toWebhook: boolean = true
): Promise<DataMessage>
```

## Writing data

### postActivity

Writes workout data into Apple Health. **iOS only** (iOS 14+) — rejects on Android.

```typescript
function postActivity(
  connection: Connections,
  payload: TerraActivityPayload
): Promise<SuccessMessage>
```

* `connection: Connections` ➡ Use `Connections.APPLE_HEALTH`.
* `payload: TerraActivityPayload` ➡ Activity data to write. Required fields: `metadata` (start\_time, end\_time, type), `device_data` (at least one field). Optional: `distance_data`, `calories_data`.

**returns** `Promise<SuccessMessage>`

## Android-only methods

These functions are **only available on Android**. They will reject with an error on iOS.

### isHealthConnectAvailable

Checks if Health Connect is available on the device. Local check, no network call.

```typescript
function isHealthConnectAvailable(): Promise<boolean>
```

### openHealthConnect

Opens the Health Connect settings screen.

```typescript
function openHealthConnect(): void
```

### grantedPermissions

Returns the Health Connect permissions currently granted to your app. Returns permission name strings like `"READ_HEART_RATE"`, `"READ_STEPS"`, etc.

```typescript
function grantedPermissions(): Promise<Array<string>>
```

## iOS-only methods

### setIgnoredSources

Filters out health data from specific apps when reading from Apple Health. Use this to prevent double-counting when a user connects a data source both through Terra's API (e.g. WHOOP, Garmin) and has that same app syncing into Apple Health.

```typescript
function setIgnoredSources(ignoredSources: Array<string>): void
```

* `ignoredSources: Array<string>` ➡ App bundle identifiers to exclude (e.g. `["com.whoop.app", "com.garmin.connect.mobile"]`).

{% hint style="info" %}

* Takes effect on the next data fetch (including background delivery).
* **Not persisted across app launches** — call this on every app start if needed.
* **Android: this function is a no-op.** It is accepted but does nothing.
  {% endhint %}