React Native

Connections

Value	Platform	Description
Connections.APPLE_HEALTH	iOS	Apple Health (HealthKit)
Connections.SAMSUNG	Android	Samsung Health (direct SDK access)
Connections.HEALTH_CONNECT	Android	Health Connect (reads all data sources)
Connections.GOOGLE	Android	Google Fit (via Health Connect, filtered to Google Fit data)
Connections.FREESTYLE_LIBRE	Both	FreeStyle Libre (NFC sensor)

CustomPermissions

Use these to request a subset of permissions. When not specified, all permissions from your developer scopes are requested. 45 values available — see the CustomPermissions enum for the full list.

Types

SuccessMessage

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

DataMessage

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

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.

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

• devID: string ➡ Your developer ID from the Terra Dashboard.

• 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>

You must await this call and verify success is true before calling any other SDK function.

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.

function initConnection(
  connection: Connections,
  token: string,
  schedulerOn: boolean,
  customPermissions: CustomPermissions[] = [],
  startIntent: string | null = null
): 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 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.

• startIntent: string | null ➡ Activity path for FreeStyle Libre NFC scan. Android only.

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.

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.

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.

toWebhook behavior:

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

Both paths require network connectivity.

getActivity

Retrieves workout and exercise session data.

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

getDaily

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

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.).

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.).

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

getNutrition

Retrieves nutrition and meal data.

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.

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.

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.

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.

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.

function isHealthConnectAvailable(): Promise<boolean>

openHealthConnect

Opens the Health Connect settings screen.

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.

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.

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

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

• 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.