> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/introduction/core-concepts.md). # 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. | Product | Takes in | Sends results to | | ----------- | ----------------------------------------- | ----------------------- | | 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](/introduction/account-setup-and-api-keys.md). | Credential | Safe to expose | Description | | ----------------------- | -------------- | -------------------------------------------------------------------------------------------------------------- | | 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](/vantage-api/account-setup-and-api-keys.md#authentication). {% hint style="warning" %} Never put your API key in client-side code, a mobile app, or a public repository. Call Terra from your server. {% endhint %} ## 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](/unified-api/understanding-terra-environments.md). ## 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. | Product | Reference ID field | | ----------- | --------------------------- | | 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](https://dashboard.tryterra.co/dashboard/connections) of the dashboard. A destination receives every event type unless you limit it with `destination_event_types`. Learn more about [destination types](https://docs.tryterra.co/reference/health-and-fitness-api/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](/vantage-api/versioning.md). ## Unified API The [Unified API](/unified-api/getting-started.md) 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](https://dashboard.tryterra.co/dashboard/connections), and see every source in the [supported integrations list](https://docs.tryterra.co/reference/health-and-fitness-api/supported-integrations#integrations-list). Sources send new data to Terra in one of two ways: | Type | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | 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_id`s 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](https://docs.tryterra.co/reference/health-and-fitness-api/data-models). | Data type | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `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](/destinations/events.md). ### 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](/lab-reports/lab-reports.md) 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](/lab-reports/core-concepts.md). ## Vantage API The [Vantage API](/vantage-api/overview.md) 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](/vantage-api/account-setup-and-api-keys.md#configure-your-webhook-endpoint), not to your destinations. Learn more about [orders, results and status lifecycles](/vantage-api/core-concepts.md). ## See also * [Account setup and API keys](/introduction/account-setup-and-api-keys.md) * [Unified API quickstart](/unified-api/quickstart.md) * [Streaming API core concepts](https://docs.tryterra.co/reference/streaming-api/core-concepts) * [Planned Workouts API core concepts](/planned-workouts-api/core-concepts.md) * [Routes API core concepts](/routes-api/core-concepts.md)