Core concepts
Understand the fundamental terms and concepts used throughout the Terra API ecosystem. Grasping these will help you integrate Terra more effectively.
Last updated
Was this helpful?
Understand the fundamental terms and concepts used throughout the Terra API ecosystem. Grasping these will help you integrate Terra more effectively.
Last updated
Was this helpful?
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.
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.
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).
What it is: Where Terra sends the processed data (e.g., your server via Webhook, SQL database, Azure Blob storage, Amazon SQS queue).
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".
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
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.
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
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.
Terra API is versioned to manage changes and improvements.
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)
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.