Overview

Discover the capabilities of Terra's Health & Fitness API, enabling you to access historical and current user health data from a multitude of health data sources.

What is Health & Fitness API?

Terra's Health & Fitness API is your primary gateway to accessing comprehensive health data in your app from your users' wearables, devices, health apps, and medical devices.

It standardises endpoints for authentication, requests, and data models across 150+ data sources.
It's event-based: user health and fitness data is automatically pushed to your destination (e.g., webhook) after authentication. API requests are therefore only needed for historical data.

Key features

🎣 Automatic payloads for new data (via Webhook)

Mechanism: Receive automated, near real-time data updates via HTTP POST requests (Webhooks) to your specified Destination endpoint.
Trigger: Webhooks are typically triggered when new data is synced from a user's wearable or app to the provider's cloud service and subsequently processed by Terra.
Content: Payloads include standardised JSON representing new or updated user data (e.g., a completed workout, daily summary, new sleep session).
Use Case: Keep your application's data for users current without needing to poll for changes. Ideal for timely insights and responsive features.

🗄️ Historical data retrieval (via GET requests)

Mechanism: Make synchronous or asynchronous GET requests to specific Terra API endpoints to fetch data for a user over a defined date range.
Scope: Access data from the point a user first connected their account to Terra, subject to provider limitations.
Use Case: Populate user profiles, establish baselines, perform trend analysis, or backfill data.
Considerations: For large data ranges (e.g., >28 days), requests are often processed asynchronously, with data delivered in chunks via Webhooks or to a specified data store.

🔑 User authentication

Mechanism: Terra provides tools (e.g., Terra Widget, or APIs to build your own UI) to facilitate the user authentication process, where users grant your application permission to access their health data via Terra.
User Identity: Terra manages user connections and provides unique identifiers for each connected data source account.

🧩 Standardised data model

Mechanism: All data retrieved from various providers is transformed by Terra into consistent, predefined JSON schemas.
Benefit: Simplifies integration by providing a uniform data structure, regardless of the original source's format. You code against one set of models.
Scope: Applies to all data types (Activity, Sleep, Body, Daily, Nutrition, etc.). Detailed schemas are available in the Data Models.

✏️ Writing data

Mechanism: Send data from your application to Terra via specific POST API endpoints, which then attempts to write this data to the connected user's account on the source provider's platform.
Supported Operations (Examples):
- Planned Workouts: Upload structured workout plans that users can access and follow on their wearable devices.
Provider Dependency: Only certain providers are supported - this depends on the features supported by the end provider's API. Not all data types or providers support write operations.

How Terra Accesses Data: Cloud APIs vs Mobile SDKs

Understanding how Terra connects to different data sources is crucial.

Type of data source

Integrations

Integration Platform

Web-based source

Garmin
Fitbit
Oura
Strava

150+ other sources

Backend Server (using the Health & Fitness API)

Mobile-only source

Apple Health
Samsung Health
Google Fit
Health Connect

No other sources

Mobile App (using the Terra Mobile SDK)

Web-based sources

The majority of Terra integrations are web-based providers (e.g., Garmin, Fitbit, Oura, Strava)

For most providers, Terra integrates directly with their Web APIs.
Whether you are building a web app or mobile app, you should integrate the API in your backend.
Once a user authenticates via the API, Terra can fetch data and send payloads (e.g. to a webhook endpoint).

Mobile-only sources

The only mobile-only sources are: Apple Health, Samsung Health, and Health Connect.

These sources do not offer Web APIs for third-party developer access.
They require a mobile app with a Terra's Mobile SDK on the user's device to fetch the data.
Your mobile app, equipped with Terra's Mobile SDK, will facilitate the connection to the on-device health data store (e.g., HealthKit on iOS, Health Connect on Android).
The Mobile SDK then securely transmits this data to Terra for processing and delivery of payloads to your configured Destination (e.g. to a webhook endpoints).

Only use the Mobile SDK if you need to

The vast majority of Health & Fitness API work via Terra's Web API (e.g., Garmin, Fitbit, Oura, Strava).

You do NOT need to use the Mobile SDK for them.

Only use the Mobile SDK if you want to integrate with the following providers:

Apple Health

Samsung Health

Health Connect

Next steps

Quickstart

Get health data from your first user via a web-based source (e.g., Garmin, Fitbit, Oura).

Learn how to setup and configure the Health & Fitness API to receive your users' data to your preferred destination (e.g. webhook, DB, etc). This includes enabling data sources, setting up data destinations, managing API access, and understanding environments.

Last updated 1 month ago

Was this helpful?