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:
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.
You can drop us an email on email@example.com to request a subscription change!
You can get support at any time either through our Discord or by emailing us on firstname.lastname@example.org
Users can be authenticated via a Terra Widget Session. The process for you as a dev is the following:
Once the user finishes authenticatingm, it is possible to obtain the authentication result in two different ways:
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?")
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
If a user authenticates a second time, their old Terra entry gets deleted
A user can connect with more than one provider. They will get a different Terra user_id for each provider.
All deauthentication requests can be made using our deauth endpoint through providing the Terra user_id
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!
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.
A callback URL (also referred to as a webhook URL) is where Terra pushes data to you. For example:
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.
We push user data to your webhook every 8 hours by default. This interval can be modified to your preference in the dev portal.
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.
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.
Terra does not impose any provenance limits on the data. The scenarios in which limits are set are:
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.
These can be modified in your dev portal settings section!