Terra Docs
Dashboard
  • Docs
  • API Reference
  • Changelog
  • Get started ⚡️ Choose your integration
  • Health & Fitness API
    • Overview
    • Set up your Integrations
    • Connect a User
    • Receive data updates
    • Request Historical data
    • Write data
    • Debugging FAQ
    • Mobile-Only Sources: Apple, Samsung, Google Fit
      • iOS (Swift)
      • Android (Kotlin)
      • React Native
      • Flutter
  • Streaming API
    • Getting Started
    • 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
  • Prerequisites
  • Data events
  • Testing
  • Common errors & troubleshooting
  • Help! My destination is erroring (retries)
  • Data is shown on my Fitbit/Garmin/etc... app, but hasn't been sent yet
  • 1. User has logged in with the wrong account
  • 2. "My data isn't syncing"
  • Google Fit

Was this helpful?

  1. Health & Fitness API

Receive data updates

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

PreviousConnect a UserNextRequest Historical data

Last updated 2 months ago

Was this helpful?

Prerequisites

In order to receive , you'll need to

  • have an active (guide )

  • have enabled the you want (guide )

If you missed any of the steps above, please refer to the respective guides.

Once you have the above set up, you'll be ready to receive events.

Terra sends updates via to your . Familiarize yourself with the types of events and their payloads:

  • occur when a user connects/disconnects their health & fitness data account

  • occur when new data is available on the user's account

  • See

Data events

Whenever a has new data available on the respective platform they use, you will receive a data update under one of the following categories

Overwriting/updating data

Whenever receiving 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.

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

Use the unique identifier for each payload (detailed below) to overwrite data appropriately upon receiving an update

Activity: A tracked workout, with a defined start and end time.
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.

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.

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.

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.

Data updates will take the following form:

{
  "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"
}

Testing

Common errors & troubleshooting

Help! My destination is erroring (retries)

If your destination returns an error code (e.g. your server responds to a webhook event with a 5XX http status code), not to worry! Terra retries to send that event, with exponential backoff, over a period of a little over 24 hours. This ensures that if your server experiences downtime of up to a day, you will still receive any missed data, hence maintaining data integrity.

Data is shown on my Fitbit/Garmin/etc... app, but hasn't been sent yet

Terra sends data automatically as soon as it is available on a data source's cloud. That means that if the wearable hasn't synced to the respective app on the end user's phone, or if the app has not synced to the cloud, Terra will be unable to retrieve that data. Wait a bit longer, or try to force a sync (using a "pull down to sync" feature or equivalent available in most apps)

In order to verify if the data has synced to the respective cloud, you may instruct the user to go on their web dashboard for their device using a browser to verify the data is present.

Some users may inquire about missing data, and you may not be sure what's going on.

Here are a few common issues & debugging steps.

1. User has logged in with the wrong account

(This happens more often than you'd think)

Some users may have logged in with the wrong account. In order to verify the account that they're using matches with the Terra user ID that they've generated, you may follow the following procedure for the integrations below.

Getting the account's user ID on the provider's end

FreestyleLibre

Often enough, users will have logged into an account with little data, really old data, or no data at all by mistake, without realizing it. You can then share a screenshot of that view with your user in order to help them log into the correct account instead.

Fitbit

Launch your Fitbit app (make sure you're using the latest Fitbit app version), click your Fitbit avatar in the top left corner, then click your Fitbit display name to view your profile. Then Click "Personal" and go to the next page, your Fitbit User ID is located at the bottom.

MyFitnessPal

Invalid username

Seeing a page like this:

indicates that the username entered by the end user is invalid. In the case above, the user accidentally entered their email instead of their username. Have them log in once more, following the "how-to" guide presented in the login screen

Disabled diary sharing

The page below:

Indicates the user failed to enable diary sharing/disabled it since they authenticated through Terra. In order to remediate this, have the user re-enable diary sharing with the same password used during initial authentication, or have them re-authenticate after having enabled diary sharing as per the "how-to" guide in the login screen

2. "My data isn't syncing"

In those cases the first step is always to ensure that the data is showing up in the partner app (e.g. Garmin Connect, Fitbit, etc..).

Next would be to check if the data is correctly synchronized with the partner cloud, by using their web portal.

Garmin

Apple Health

The most likely culprit would be background app refresh being turned on/background updates not working as expected. In order to verify this, first request a backfill (requires TerraiOS >= 1.6.12) through your Terra Dashboard, in Tools > Debug > Users for that specific user_id.

If data does come through, this means that background delivery is not operating as expected. To Troubleshoot, follow the steps below.

Culprit 1: Battery saving mode is on

For this, have the user go to Settings > Battery, and make sure "Low Power Mode" is turned OFF

Culprit 2: Background app refresh is turned off for your app

For this, have the user visit Settings > General > Background App Refresh, and verify that your app is toggled on

Google Fit

Go inside the Google Fit app, and ensure that your data is up to date on the display. Thereafter, pull down from the top of the screen to synchronize with the cloud. Please note that even after that, there can be some delay for Google to make the data available through their API. You should be able to see that data after at most 30-60 minutes in most cases.

iOS-specific

Ensure background app refresh is turned on for Google Fit

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

Planned Workout: a step by step workout plan for the

Any other event types & their explanations will be found in the reference

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.

Terra always a user_id for each connection. To get the user ID that the provider (e.g. Garmin, Fitbit etc) uses, you can use the endpoint in order to retrieve that, which will be under the field provider_user_id. Once you have obtained that, follow the guidelines below for each provider.

For FreestyleLibre, a user's profile URL takes the form .

If we have connected your users to your own Libreview practice, you may simply substitute provider_user_id with the one retrieved from the endpoint and visit the link above. You'll then be able to see the user's account email, name, and data present on their account, by clicking on the "Glucose History" tab.

Check to make sure your user's Fitbit user ID matches the one retrieved by the endpoint

Using the provider_user_id obtained above, navigate to .

Ensure that the data is showing up in . If not, then pull down from the top in the Garmin connect mobile app, and hit the circle arrow until everything refreshes. If the data shows up in the web dashboard for Garmin Connect, but not through the API after 1-2 minutes, please contact support.

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
the payload simulator
https://www.libreview.com/patient/{provider_user_id}/profile
https://www.myfitnesspal.com/food/diary/{provider_user_id}
the Garmin connect web dashboard
events
Data events
Common errors and troubleshooting
Authentication events
here
here
#athlete
#athlete
#athlete
Destination
Data Sources
events
destination
User
User
User
GET activity
User
GET daily
User
GET body
User
GET sleep
User
GET menstruation
end user
User
Event Type
here