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
  • Terra credentials
  • Developer ID
  • API Key
  • Data flow & Connections
  • Source (Provider/Integration)
  • Destination
  • User (Terra user)
  • End User (The person)
  • Reference ID
  • Data & events
  • Event
  • Data types
  • Large Request
  • Integration mechanisms
  • Event-driven integrations
  • Polled integrations
  • API Versions
  • Major API versions
  • Minor API versions

Was this helpful?

  1. Getting Started

Core concepts

Understand the fundamental terms and concepts used throughout the Terra API ecosystem. Grasping these will help you integrate Terra more effectively.

PreviousAccount setup and API keysNextOverview

Last updated 21 days ago

Was this helpful?

Terra credentials

Developer ID

  • What it is: Your Developer ID dev-id is your unique identifier as a developer on the Terra platform. Think of it like your username.

  • Its role: Terra uses this to identify you and associate connected and their data back to your account.

  • Security: Not sensitive; can be publicly available.

  • Where to find it: of your Terra Dashboard.

Think of your dev ID like your username

It does not constitute sensitive information. Making it publicly available is not a security concern.

API Key

  • What is is: Your API key is your secret access token for the API. Think of it like your password.

  • Its role: Authenticates your application's requests, verifying you're the legitimate developer behind the dev-id.

  • Security: Highly sensitive; treat it like a password and never expose it publicly or in client-side code.

  • Where to find it: of your Terra Dashboard.

Think of your API Key like your password

It constitutes sensitive information. Making it publicly available is a big security risk


Data flow & Connections

Source (Provider/Integration)

  • What it is: A Source (also referred to as a Provider, or Integration) is the origin of health and fitness data (e.g., Fitbit, Garmin, Apple Health).

Destination

  • What it is: Where Terra sends the processed data (e.g., your server via Webhook, SQL database, Azure Blob storage, Amazon SQS queue).

User (Terra user)

  • What it is: Represents a connection made through Terra to a specific fitness wearable account (e.g., one Fitbit account, one Garmin account).

  • For reference: Throughout this documentation, a connection made to one fitness wearable account (e.g. one Fitbit account, or one Garmin account) will be referred to as "one User".

End User (The person)

Reference ID

  • Purpose: The reference_id should be the identifier of the End User on your systems. This could be the End User's username, their email address, or any way in which you identify them.

  • How you use it: When creating a User, you will have the option of passing in a reference_id to conveniently link it back to an End User


Data & events

Event

Data types

  • Concept: Categories of health and fitness information Terra processes. Each has a defined structure.

  • Examples:

    • Activity: A completed workout session (not currently active or planned) by the user, with a defined start and end time. For example, this corresponds to when a user would press "start workout" on their Garmin smartwatch, go for a run, then press "end workout".

    • Daily: A summary of the total activity completed by a user for a given 24 hour period, defined by the start and end time of the payload.

      • These payloads will be sent multiple times throughout a given day, as a user moves around, and will be a total of their activity up until that point in the day.

      • When ingesting Daily events, always overwrite data for a given date with the latest one sent to your Destination.

    • Body: This represents the various Body metrics for a user for a given 24 hour period, defined by the start and end time of the payload.

      • These payloads will be sent multiple times throughout a given day, as a user generates more body-related metrics (weigh-ins, blood glucose measurements etc), and will be a total up until that point in the day.

      • When ingesting Body events, always overwrite data for a given date with the latest one sent to your Destination.

    • Menstruation: This represents a day in the user's menstrual cycle, and includes information about that day within the context of their overall monthly cycle, such as current phase, and any metadata associated with that day (bleeding level, feelings of nausea, etc).

    • Nutrition: This represents the various food logged by a user for a given 24 hour period, defined by the start and end time of the payload.

      • This will be data logged in Food Diary apps such as MyFitnessPal, Fitbit or MacrosFirst. Each meal represents a given food item logged within that day.

Large Request

    • At most 10MB

    • At most 10 objects within the data array

    • Whichever limit of the two gets hit first will determine the chunk's size


Integration mechanisms

Event-driven integrations

Polled integrations

  • How it works: Integrations that are Polled do not have an event-sending system, and require Terra to periodically check for data updates by polling their servers. This will be done as often as every 5 minutes.


API Versions

Terra API is versioned to manage changes and improvements.

Major API versions

  • Indication: Significant architectural changes to API endpoints and infrastructure. These API versions are very infrequent.

  • Identification: You will identify these with the base URL (i.e. api.tryterra.co/v2, api.tryterra.co/v1, and access.tryterra.co are 3 separate major versions)

Minor API versions

  • Indication: Smaller updates, often non-breaking.

  • Identification: You can identify these by the version included in every payload you receive from Terra, and will be versioned by date.

    • For example, at the time of writing, the latest API version is 2022-03-16. The version prior to it was 2022-03-02.

    • Only breaking changes to the API are versioned. Any non breaking changes will be continuously developed, tested, and deployed.

Management: You can enable or disable Sources via your , controlling the flow of data.

List of sources: You can view a list of all available health data sources .

Customisation: Configure your active Destination in the .

List of destinations: You can view a list of all available destinations .

Key point: A single (a real person) might have multiple Terra Users if they connect different wearable accounts (e.g., both their Fitbit and their Garmin). Each connection creates a new Terra User ID.

What it is: The actual individual who owns the wearable devices and whose data is being accessed. An End User can be associated with multiple .

What it is: An identifier you provide to link a back to an in your own system.

What it is: A piece of data, typically a JSON object, sent to your .

Types: Can be specific (like an activity or sleep session) or a metadata event (e.g., authentication success).

Sleep: A sleep session completed by the . The start time and end time can be representative of the time that the user got in bed instead of the time that they fell asleep at, if tracked by the wearable device - potentially including time in bed vs. time asleep.

What it is: A request spanning more than 28 days (unless defined otherwise).

Processing: This type of request will always be processed asynchronously, and sent to your in chunks. The chunks sent to you will each be of either:

How it works: Integrations that are Event-Driven allow for the fastest data retrieval speeds. As soon as new data is synced from the user's wearable's app (e.g. the Fitbit app) to the cloud, a notification (or event) gets sent to Terra with the newest data, following which Terra sends you a to your with the latest available data.

Terra Dashboard
Terra Dashboard
Credentials section
Credentials section
Users
End User
Terra Users
Terra User
End User
Destination
Data Types
user
data
destinations
Provider's
payload
Destination
here
here