Core concepts
Learn the terms and building blocks shared across Terra products.
Your Terra account has one or more environments, such as testing and production. Each environment has its own credentials, users and destinations, and every Terra product you use works inside it.
Unified API
Data from wearables and health apps
Your destinations
Lab Reports
Lab report files and DXA scans you upload
Your destinations
Vantage API
Test orders you place
The Vantage webhook URL
Credentials
Every Terra product uses the same two credentials. Find both under API keys in the header bar of the Terra Dashboard. Learn more about account setup and API keys.
Developer ID (dev-id)
Yes
Identifies one environment in your account. It works like a username.
API key (x-api-key)
No
Authenticates your requests and proves they come from the owner of the developer ID. Treat it like a password.
Send both as headers on every request. The Vantage API also accepts them as HTTP Basic auth.
Environments
Each environment has its own developer ID. Users, destinations and settings belong to one environment and are not shared with the others, so you can build and test without touching production data. Learn more about Terra environments.
End users and reference IDs
An end user is the real person whose data you are working with: the person wearing the device, uploading the lab report, or taking the test.
Terra does not know who the end user is in your system. When you connect a wearable, upload a report or place an order, pass your own ID for that person, such as a username, email address or database ID. Terra stores it as a reference ID and returns it with the result, so you can match the data back to the right person.
Unified API
reference_id
Lab Reports
reference_id
Vantage API
client_order_reference_id
Destinations
A destination is where Terra sends what a product produces: a webhook on your server, a SQL database, cloud storage such as Amazon S3, a queue such as Amazon SQS or Kafka, or a database such as MongoDB, Firestore or Supabase. Add destinations on the Connections page of the dashboard.
A destination receives every event type unless you limit it with destination_event_types. Learn more about destinations.
Events
An event is a JSON payload Terra sends to tell you something happened, such as new data arriving or a status changing. Each product has its own events, described in its section below.
API versions
Terra versions its APIs by date. A breaking change ships under a new date. Additive changes, such as a new field, reach every version.
Choose a version for a request with the X-Terra-Version header. Without it, the request uses the version your account is pinned to, which is the latest version at the time of your first request.
One date works across every product. Each product serves its newest version on or before the date you send. For example, if you send 2026-10-25, the Vantage API serves its 2026-10-15 version and Lab Reports serves its 2026-10-21 version. Learn more about versioning.
Unified API
The Unified API reads health and fitness data from wearables and apps and sends it to your destinations in one format.
Sources
A source is where health and fitness data comes from, such as Fitbit, Garmin or Apple Health. Other pages also call a source a provider or an integration. Enable sources on the Connections page, and see every source in the supported integrations list.
Sources send new data to Terra in one of two ways:
Event-driven
The provider notifies Terra as soon as the wearable's app syncs new data to the provider's cloud. This is the fastest way to get new data.
Polled
The provider has no notifications, so Terra checks its servers for new data every 15 minutes by default, and never more often.
Users
A user is one connection between Terra and one wearable account, such as one Fitbit account or one Garmin account. Each user has its own user_id, and Terra returns your reference_id on the user in every event.
One end user can have several users. If someone connects both their Fitbit and their Garmin, Terra creates two users with different user_ids that share one reference_id.
If an end user connects the same provider account again with the same reference_id, Terra replaces the old user with a new one, with a new user_id. Connecting a different account on the same provider adds a second user and leaves the first in place.
Data types
The Unified API has eight data types, each with a fixed structure. Learn more about every field in the data models reference.
activity
One completed workout with a start and end time, such as a run recorded between pressing start and stop on a Garmin watch.
athlete
The end user's profile on the provider, such as name, age, sex, location and devices.
body
The end user's body metrics for one day, such as weigh-ins and blood glucose readings.
daily
The end user's total activity for one day.
hormone
One hormone test, with levels such as LH, FSH and hCG.
menstruation
One day of the menstrual cycle: the current phase and anything logged that day.
nutrition
The food an end user logged in one day, from apps such as MyFitnessPal.
sleep
One completed sleep session. If the device tracks it, the start time can be when the end user got into bed rather than when they fell asleep.
daily and body payloads arrive several times a day. Each one holds the running total for that day so far, so overwrite the stored payload for that date with the latest one.
Event delivery
Terra sends each event to each of your destinations as a separate delivery. A delivery is one or more attempts: the first send, plus any retries and resends. Learn more about event delivery.
Large requests
A request for more than one calendar month of data is a large request. Terra processes it in the background and sends the data to your destinations in chunks of 10 MB or less, so a large request must use to_webhook=true, which is the default.
Lab Reports
Lab Reports turns lab report PDFs, images and DXA scans into structured biomarker data.
Each upload creates a session, which tracks the report through extraction, standardization and delivery. Terra classifies the file as a clinical lab report or a DXA scan, matches each result to a known biomarker, and maps its unit to a standard UCUM code. It does not convert values between units.
When processing ends, Terra sends a lab_report.completed or lab_report.failed event to your destinations. Learn more about sessions and delivery.
Vantage API
The Vantage API orders blood and DNA tests and returns the results.
You order from a catalog of products, grouped by product type such as blood or DNA. Each product has variants, and a variant is what you order. Samples are collected at home, by kit or a visiting phlebotomist, or at a lab.
An order is one purchase for a recipient, and holds one or more order items. Each order item is tracked on its own: kit activation, results and acknowledgment all belong to the order item. The person who takes the test, the test taker, can be someone other than the recipient.
Vantage sends an event when an order's fulfilment status or an order item's results status changes. It sends events to one webhook URL per environment, not to your destinations. Learn more about orders, results and status lifecycles.
Streaming API
The Streaming API sends live readings, such as heart rate, from a wearable to your backend over WebSockets while the end user wears it.
Device
A wearable that streams over Bluetooth Low Energy (BLE), ANT+, or its own Bluetooth protocol (Apple Watch, Wear OS and Samsung watches).
Phone
The end user's iOS or Android phone. It connects to the device and runs your app with the Terra RT SDK.
Producer
A connection that sends data to Terra. The RT SDK on the phone is the producer.
Broker
Terra. It receives data from producers and passes it to every consumer connected to that stream.
Consumer
A connection that receives the stream, usually your backend.
Each WebSocket connection authenticates with its own short-lived token, minted by your backend. Learn more about streaming authentication.
See also
Last updated
Was this helpful?