Terra Docs
Dashboard
  • Docs
  • API Reference
  • Changelog
  • Getting Started
    • What is Terra API?
    • Account setup and API keys
    • Core concepts
  • Health & Fitness API
    • Overview
    • Quickstart
    • Integration setup
      • Understanding sources and destinations
      • Setting up data sources
      • Setting up data destinations
        • Webhooks
        • SQL database (Postgres, MySQL)
        • Supabase
        • Cloud storage (S3, GCP)
        • Queuing services (SQS, Kafka)
      • Customising data types
      • Dedicated data source API keys
      • Understanding Terra environments
    • User authentication
      • Authentication flow
      • Implementation (Terra widget)
      • Implementation (Custom UI)
      • Handling authentication events
      • Customising authentication redirects
    • Managing user health data
      • Receiving health data updates (events)
      • Requesting historical health data (REST API requests)
      • Writing data
    • Mobile-only sources
      • iOS (Swift)
      • Android (Kotlin)
      • React Native
      • Flutter
    • Troubleshooting
    • Pricing
  • User Engagement
    • Health Scores
  • Streaming API
    • Overview
    • Wearable -> Your app
      • iOS (Swift)
      • Android
    • Your app -> Terra
      • iOS (Swift)
      • Android
    • Terra -> Your backend
  • Teams API
  • Biomarkers API - Upcoming
Powered by GitBook
On this page
  • 1. Types of Health Data Events
  • 2. How to test your Destination?
  • 3. FAQ: Common errors & troubleshooting
  • ✅ Checklist

Was this helpful?

  1. Health & Fitness API
  2. Managing user health data

Receiving health data updates (events)

Learn how to receive data update events to your app as soon as the user's data syncs to the cloud

PreviousManaging user health dataNextRequesting historical health data (REST API requests)

Last updated 14 days ago

Was this helpful?

Terra API simplifies health & fitness data syncing: once you connect a user, Terra automatically manages token refreshes, authentication updates, and delivers all health and fitness data directly to your Webhook/DB as soon as it’s available.

Requesting data is not required unless you need to backfill historical data, to debug, or as a fallback. This lets you focus on your app while Terra handles the data flow and reliability.

In this section, you will learn about:

  1. : sent to your destination when new data is available on the user's account.

  2. : Terra sends to your , learn how to test this.

  3. : when not receiving expected data.

Prerequisites

In order to receive Data as Events, you'll need to:

  1. Obtain your API Key from your Terra Dashboard

  2. Set up a data destination where Terra will send event and data updates.

  3. Enable the specific data sources your app requires (e.g., oura, garmin, etc).

  4. Connected at least a user.

    1. If not, then no worries, you can use the to test sending data to your destination!

    2. However, make sure to familiarize yourself with Authentication Events.


1. Types of Health Data Events

Data Events fall under one of the following categories:

(1) Activity: A tracked workout, with a defined start and end time.
(2) Daily: the total daily summary of the user's activity up to the point in time of the event

This can be the cumulative number of steps, calories burned, etc. daily payloads are always relevant to a given 24 hour period, defined by the start_time and end_time of the metadata key. When parsing, only consider the date part of the field, and ignore the time.

(3) Body: the recorded body metrics for the user for a given day

body payloads are always relevant to a given 24 hour period, defined by the start_time and end_time of the metadata key.

(4) Sleep: a tracked sleep session, with a defined start and end time.

This can include time spent in bed while awake, if recorded by the wearable.

(5) Menstruation: menstrual metrics for the user for a given day

E.g. the phase they're currently on, their blood flow for the day, etc. menstruation payloads are always relevant to a given 24 hour period, defined by the start_time and end_time of the metadata key.

You can find all your received events (payloads) in:

Overwriting/Updating data

  • This means you should always overwrite data stored on your end with the most up-to-date version.

  • Depending on the event type, use the unique identifier for each payload to overwrite data appropriately upon receiving an update (e.g. metadata.start_date, metadata.summary_id, etc). These unique identifiers are found in the category descriptions listed above.

Example of a Health & Fitness Payload

Data Events will take the following form:

ActivityPayload.json
{
    "type": "activity",
    "data": [
        {
          "metadata": {
                "type": 45,
                "start_time": "2024-10-03T18:17:45.000000+08:00",
                "city": null,
                "name": "MEDITATION",
                "state": null,
                "upload_type": 1,
                "country": null,
                "summary_id": "f09554ca56fde426de5d7f9c34fc0e1e3ff015c2ae253b39",
                "end_time": "2024-10-03T18:38:39.000000+08:00"
          },
          ..... ommitted for brevity
        }
    ],
    "user": {
        "reference_id": "2397",
        "active": true,
        "user_id": "9d5dc9eb-3e02-4b37-9a7b-b14b5a5a2b93",
        "last_webhook_update": "2024-10-03T11:13:43.360227+00:00",
        "created_at": null,
        "scopes": "fitness.sleep.read,fitness.body.read,fitness.body_temperature.read,fitness.activity.read,fitness.blood_pressure.read,fitness.location.read,calendar.settings.readonly,fitness.reproductive_health.read,userinfo.email,user.birthday.read,user.gender.read,fitness.oxygen_saturation.read,fitness.heart_rate.read,userinfo.profile,fitness.nutrition.read,fitness.blood_glucose.read",
        "provider": "GOOGLE"
    },
    "version": "2022-03-16"
}

2. How to test your Destination?

3. FAQ: Common errors & troubleshooting


✅ Checklist

Receiving data Updates

  1. Set-up: Have you tested that your destination can receive data payloads from Terra?

  2. Connect a User: Have you connect a user via Terra? Have you received an Authentication Event?

  3. Receiving Data: After completing an event (e.g. activity), did you receive a Data Event "Activity"?

Whenever a has new data available on the respective platform they use, Terra will send a Data Event to your Data Destination.

Unique identifier (per ): metadata.summary_id

For example, an pressing "start run" on their watch, going for a 5k run, and pressing "end run"

See for the full Schema & descriptions of each field

Unique identifier (per ): metadata.start_time

See for the full Schema & descriptions of each field

Unique identifier (per ): metadata.start_time

See for the full Schema & descriptions of each field

Unique identifier (per ): metadata.summary_id

See for the full Schema, example, & descriptions of each field

Unique identifier (per ): metadata.start_time

See for the full Schema, example, & descriptions of each field

(6) Planned Workout: a step by step workout plan for the

You can find more details about these Data Events in the reference.

Your .

Whenever you receive an event for a which constitutes a duplicate, based on the data type's unique identifier (detailed in each section below), the received data will always be a superset of any previous data received.

For testing out the different event types mentioned above, you may also use in the Terra Dashboard. See the tutorial below for a step by step guide.

Found in

If you didn't receive an expected payload after a long time, please refer to our to ensure the user's data is synced properly.

Unique identifier (per ): metadata.summary_id

A planned workout, with a defined set of steps/reps/sets to be followed. For example, 15 min running at 7:00 pace, followed by 3x repetitions of 100m sprints with 45s jog at 8:00 min pace in between. See for more info

End User
Terra Dashboard > Payload History
the payload simulator
Debugging FAQ.
Debugging FAQ
How to test your Destination
API Key:
Payload Simulator
Health Data Events
Common errors and troubleshooting
Destination Configured:
Data Sources Enabled:
events
destination
here
User
User
GET activity
User
GET daily
User
GET body
User
GET sleep
User
GET menstruation
end user
User
Event Type
User