What is Terra and how does it work?

Different wearables have different data models, endpoints, fetch protocols, or even documentations. This results in time consuming, unstable, and numerous integrations for developers.

Terra provides an API to connect to all these different wearbles through a single integration, unifying all wearables under a single language.

Integrating with Terra is very simple:

  • You request a user authentication link from Terra
  • You redirect your user to the link
  • The user is automatically prompted to select a wearable and connect to Terra
  • You receive user data following the Terra standard regurlary or on-demand to a webhook endpoint of your choice

That's it! The Terra standard unifies all wearable data standards into a single language, enabling you to focus on integrating your product on top of the data.

How do I change my subscription?

You can drop us an email on dev@tryterra.co to request a subscription change!

Where can I get further technical or general support?

You can get support at any time either through our Discord or by emailing us on dev@tryterra.co๏ปฟ


How do I authenticate a new user (with/without Widget)?

Users can be authenticated via a Terra Widget Session. The process for you as a dev is the following:

  • Request a widget session from Terra using the widget endpoint๏ปฟ
  • Present the obtained session to the user

Once the user finishes authenticatingm, it is possible to obtain the authentication result in two different ways:

  • Terra will push to your webhook the authentication outcome (success, user_id, wearable)
  • The session URL will redirect the user to a success page (set by you). The URL will contain the user_id and the wearable

More information about the authentication flow using a widget session can be found on our docs!

Some providers do not require authenticating using a widget session, and instead the authentication can be done using our SDKs on the user device directly (more about that under "Why does authenticateUser endpoint not work for Apple/Samsung?")

Can you provide more information on the usage of reference_id field when generating a session for the widget?

The reference_id field is a unique identifier which you can provide when requesting a widget session. The reference_id then gets added to the webhook response we push to you after the user finishes the authentication flow.

The reference_id field can be useful in various scenarios. For example, you might have your own user identifiers. If you set this value in the reference_id, you are able to link an authentication result to one of your user identifiers, and therefore link a Terra user_id to a corresponding user on your end

What happens if a user authenticates twice to the same provider?

If a user authenticates a second time, their old Terra entry gets deleted

What if a user wants to connect with more than one provider?

A user can connect with more than one provider. They will get a different Terra user_id for each provider.

How can I deauthenticate a user if they wish to do so?

All deauthentication requests can be made using our deauth endpoint through providing the Terra user_id

Why does authenticateUser endpoint not work for Apple/Samsung?

Apple Health and Samsung Health do not provide web APIs. Therefore, authenticating a user for these providers invoking access or connecting to Terra on the user device directly. We simplify this flow by providing SDKs for such cases. You can read more about our SDKs here!

Requesting Data

How do I start pulling data?

As soon as a user connects using one of your widget sessions, you automatically start receiving regular data pushes do your callback URL!

Data can also be requested on demand by using our various data endpoints.

What is meant by a callback URL and why is it needed?

A callback URL (also referred to as a webhook URL) is where Terra pushes data to you. For example:

  • After a successfull user authentication
  • Regular pushes of user data
  • User data on demand when you request it using our data endpoints

Can I receive data by just using HTTP responses?

Yes! In your data request, you can set to_webhook to false if you'd like to receive the data in the HTTP response instead.

How often do I receive data on my webhook URL?

We push user data to your webhook every 8 hours by default. This interval can be modified to your preference in the dev portal.

Can you provide us with a sample data payload you send to us?

Below is a data payload example for daily data:


You can also send sample payloads to your webhook via the dev portal using the data generator.

Where can I find more information about the data sent to us?

Our docs describe in details the different data models and data endpoints. You can also reachout on discord or dev@tryterra.co!

How are the start_time and end_time parameters set? Are they timezone specific?

You can set the start_date and end_date parameters in your request payload (by default end_date , if not set, is one day after start_date). These dates are used to set the time range on the data requested.

The API accepts UNIX timestamps for both dates to avoid confusions. Otherwise, Terra fetches all the data based on UTC time.

I want to request a large amount of data. Is there any limits to the dates I can request?

Terra does not impose any provenance limits on the data. The scenarios in which limits are set are:

  • A provider limit on a date range chunk (e.g. a provider not allowing more than 30 days chunks)
  • A provider limit on a historical range (e.g. a provider not allowing access to data older than 2 years)
  • A date limit for when the user didn't have the wearble (e.g. if the started using their wearable in 2019, data cannot be requested for 2018)

In addition, technical timing limits are imposed when sending data over HTTP. In the case of large payloads that can timeout over HTTP, the data is automatically sent asynchronously over the callback URL instead.

How do I change my details (i.e webhook url, webhook intervals, dev_id etc)?

These can be modified in your dev portal settings section!


Updated 24 Mar 2022
Did this page help?