How the integration works

Setting up a Terra integration involves three things:

1. Authentication: how your users allow Terra to read their data

2. API pull: how Terra retrieves data from your platform (always required)

3. Webhooks: how your platform notifies Terra when new data is available (optional but highly recommended)

  ┌─────────────────────┐                    ┌─────────────────────┐
  │                     │  ─── API pull ───▶ │                     │
  │   YOUR PLATFORM     │                    │     TERRA API       │
  │                     │  ─── Webhooks ───▶ │                     │
  └─────────────────────┘                    └─────────────────────┘

1 - Authentication

When one of your users wants to connect their account to a Terra-powered app, they go through your platform's own login and consent screen. They approve what data to share. Terra never sees their password.

The result is a token: a secure key that Terra stores and uses to request data on that user's behalf. Terra handles renewing it automatically when it expires.

OAuth 2.0 is the recommended path. If your platform supports it, you can fast-track your application by filling in the form at partners.tryterra.co.

No API or not using OAuth 2.0? You can still become a partner. Reach out to us at [email protected] and we'll work with you directly.

2 - API pull

Terra calls your API to retrieve user data. This always happens when a user first connects: Terra pulls their recent history so developers have data to work with immediately. After that, Terra continues to call your API on a regular schedule unless you support webhooks (see below).

What Terra needs from you:

• The endpoint URLs for each data type you support (sleep, activity, daily stats, etc.)

• How to authenticate the request

• How to pass a date range and user ID

• A full example of what your API returns

Terra takes care of transforming your response format into a standardised schema that developers can use.

3 - Webhooks (optional but highly recommended)

If your platform can send a notification to Terra each time a user syncs their device or logs data, Terra will use that instead of regularly polling your API. This means faster, real-time data delivery and less load on your API.

How it works: your system sends a POST request to Terra's endpoint each time an event occurs. Terra verifies the request, identifies the user, and processes the data.

What Terra needs from you:

• Confirmation that your system can POST to Terra's webhook endpoint

• A full example of the event payload you send

• Which field in the payload contains the user_id (so Terra can match the event to the right user)

• A shared secret for request verification (Terra uses HMAC)

You send data in your own format. Terra handles the mapping.