All Terra requests can be downloaded as a postman collection here

1. Connect an account

Users

Terra holds the concept of Users in which each TerraUser is a an object with the following structure

{
    "user_id": String,  // not nullable
    "provider": String,  // not nullable
    "last_webhook_update": String //ISO8601 formatted string
}

📘

Concept of a User object

A user is one connection to one provider. If you'd like to connect multiple wearables to one of your users, this will require multiple TerraUser objects

You can create users by using a Terra Connect authentication session

Authentication

In order to authenticate your first TerraUser, use the appropriate TerraConnect endpoint and make a request as shown below

curl --location --request POST 'https://api.tryterra.co/v2/auth/generateWidgetSession' \
--header 'dev-id: YOUR_DEV_ID' \
--header 'X-API-Key: YOUR_API_KEY' \

❗️

Credentials

Make sure to replace YOUR_DEV_ID and YOUR_API_KEY with the appropriate credentials, found in your Terra Dashboard's API customization page

You'll receive a JSON response that looks like the following

{
    "expires_in": 900, //Length of the auth session, in seconds
    "session_id": SOME_SESSION_ID, //unique ID for the session
    "status": "success",
    "url": "https://widget.tryterra.co/session/SOME_SESSION_ID" //URL to access the session
}

From which you can copy & paste the URL into your browser, select a provider, and authenticate.

Upon the final redirection, your URL will look like the following:

https://widget.tryterra.co/session/demo/success?user_id=SOME_USER_ID&resource=SOME_PROVIDER

Where the authenticated user ID will be available as a query parameter for convenience. You can copy this user ID and save it somewhere for convenience

🚧

User creation

The newly created TerraUser object will also be sent to your webhook

2. Request Data

Once you've connected an account and saved the User ID provided, you can now make data requests.

These can be made for:

• Activity - event recorded for a specific workout
• Athlete - user information
• Body - data relating to body measurements, such as weight, height, glucose etc...
• Daily - daily summary of a user's total activity such as steps, distance, etc...
• Menstruation - log of a user's menstruation data
• Nutrition - log of a user's nutrition data, including both individual meals and a daily summary
• Sleep - events recorded for sleep sessions

You can now try this out for yourself with your newly created TerraUser Make a request with the format:

curl --location -g --request GET 'https://api.tryterra.co/v2/activity?to_webhook=false&user_id=YOUR_USER_ID&start_date=2022-07-20&end_date=2022-07-22&to_webhook=false' \
--header 'dev-id: YOUR_DEV_ID' \
--header 'X-API-Key: YOUR_API_KEY'

Query parameters to include:

to_webhook': set to false for testing - this ensures you get the data in the HTTP response and not [asynchronously sent to your webhook](doc:getting-data-into-your-project) user_id: the user ID of the user created in step 1 start_date: ISO8601 date string for which you want to query end_date`: ISO8601 date string for which you want to query

You should now receive the requested data in the HTTP response.

3. Data updates

Ideally, you will want to automatically receive up-to-date data without having to query the API for it.
To do that, set up a webhook endpoint - essentially an endpoint on your server which accepts HTTP POST requests.

Once done, make sure you handle each event type appropriately.