> 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/unified-api/quickstart.md).

# Quickstart

Connect a wearable and see its data arrive, in four steps from the Terra dashboard.

Terra connects your users' wearables and health apps, then sends their data to you. This page walks through that once, from the [Terra dashboard](https://dashboard.tryterra.co/), using your own wearable account as the test user. No code needed.

{% embed url="<https://www.youtube.com/watch?v=rkvKe4xefwY>" %}
2 minute video walkthrough
{% endembed %}

## Before you begin

* A Terra account. See [Account setup](/introduction/account-setup-and-api-keys.md).
* A wearable or health app account to connect, such as Fitbit, Oura, or Garmin.
* Somewhere to receive data. [webhook.site](https://webhook.site/) gives you a URL that shows every payload Terra sends, with nothing to install. Step 2 also covers running your own local server.

## Steps

{% stepper %}
{% step %}

#### Choose your data sources

Go to **Sources** in the dashboard and enable the wearables and apps you want your users to connect. Enable the one you own for this test.

<figure><img src="https://464213908-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVGMJVuZnZyOtvV4b53cY%2Fuploads%2Fgit-blob-7974fdf20bf6f7febd2620c38830f73b09b0a193%2FCapture%20d%E2%80%99%C3%A9cran%202025-05-16%20%C3%A0%2018.21.38.png?alt=media" alt="The Sources page of the Terra dashboard"><figcaption><p>Enabled sources are the ones your users can pick from</p></figcaption></figure>
{% endstep %}

{% step %}

#### Choose where data goes

Go to **Destinations**, add a **Webhook**, and paste your webhook.site URL. Terra sends every user's data here as it becomes available.

<figure><img src="https://464213908-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVGMJVuZnZyOtvV4b53cY%2Fuploads%2Fgit-blob-f0fea8e4c765266587e9af560ce2fba2cde8e25e%2FCapture%20d%E2%80%99%C3%A9cran%202025-05-16%20%C3%A0%2018.30.23.png?alt=media" alt="The Destinations page of the Terra dashboard"><figcaption><p>A webhook is the simplest destination. Databases and cloud storage are also supported.</p></figcaption></figure>

{% hint style="info" %}
**Two ways to get a webhook URL**

**webhook.site**: open [webhook.site](https://webhook.site/) and copy *Your unique URL*. Payloads appear on the page as they arrive. Nothing to install.

<img src="https://464213908-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVGMJVuZnZyOtvV4b53cY%2Fuploads%2FK8OxsTJyx4dIiVl8JxF9%2Fimage.png?alt=media&amp;token=d02d5923-0759-4520-9d23-adddc105aa6d" alt="webhook.site showing the unique URL to copy" data-size="original">

**Your own server**: run a small web server on your machine, then expose it to the internet with [ngrok](https://ngrok.com/). `ngrok http 8080` prints a public URL to paste into the dashboard.

```python
import flask

app = flask.Flask(__name__)

@app.route("/", methods=["POST"])
def receive():
    print(flask.request.get_json())
    return "", 200

if __name__ == "__main__":
    app.run(host="localhost", port=8080)
```

{% endhint %}
{% endstep %}

{% step %}

#### Connect a wearable

Go to **Authentication**. This page previews the Terra widget, the screen your users see when they connect. Open it, pick the source you enabled, and log in with your own account.

This is the flow your users will go through, so the login is the provider's own, not Terra's.
{% endstep %}

{% step %}

#### See the data arrive

Switch to your webhook.site tab. The first payload is an `auth` event confirming the connection. Data payloads follow as the provider syncs: `activity`, `sleep`, `daily`, `body`, and `nutrition`.

To see a data payload right away, go to **Payload Simulator** in the dashboard and send a sample to your destination.
{% endstep %}
{% endstepper %}

That is the whole loop: a user connects once, and Terra keeps sending their data to your destination.

## Do it with your coding agent

If you use Claude Code, Cursor, or another coding agent, paste this prompt. The agent does the steps above through the Terra CLI and reports back.

{% prompt description="Run the quickstart with your coding agent" icon="terminal" openInAIProviders="true" defaultExpanded="full" %}

```markdown
Set up my Terra testing environment: enable Fitbit and Oura, add a webhook destination pointing at my webhook URL, and give me the dev-id and API key. Then create a widget session for reference_id demo-user and open the URL for me. Once I have connected, confirm the connection is active and show me the first event Terra delivered.

Use the Terra CLI: brew install tryterra/tap/terra, or npm install -g @tryterra/cli, then terra login. Run terra docs ask --question "<question>" for anything you need from the Terra docs, and terra <command> --help for usage.
```

{% endprompt %}

## Build it into your app

Your app repeats the same four steps, with two differences.

* **Your app opens the widget for each user.** Your backend creates a widget session with one API call and sends the user to the URL it returns. See [Implementation (Terra widget)](/unified-api/user-authentication/implementation-terra-widget.md). The call needs your API keys, found under **API Keys** in the dashboard.
* **Your server receives the data.** Replace webhook.site with your own endpoint. See [Webhooks](/unified-api/integration-setup/setting-up-data-destinations/webhooks.md) for handling payloads and verifying they came from Terra.

<figure><img src="https://464213908-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVGMJVuZnZyOtvV4b53cY%2Fuploads%2FVaBoW97WCFpvgUPqk4GA%2Fimage.png?alt=media&amp;token=3fb51ccc-b859-43c8-9e41-6bc91d7fc700" alt="The API Keys page of the Terra dashboard"><figcaption><p>Your dev-id and API key. Keep the key on your server, never in an app or web page.</p></figcaption></figure>

Each connection gets a `user_id` from Terra. Every payload carries it, and it is how you request that user's data. Pass your own identifier as `reference_id` when you open the widget, and Terra returns it alongside the `user_id` so you can match the two. See [Core concepts](/introduction/core-concepts.md).

## Next steps

* [Unified API example app](https://docs.tryterra.co/developer-tools/example-apps/terra-basecamp): a complete integration you can scaffold with one command.
* [Requesting historical data](/unified-api/managing-user-health-data/requesting-historical-data.md): get data from before the user connected.
* [Mobile-only sources](/unified-api/mobile-only-sources.md): Apple Health, Samsung Health, and Health Connect need the mobile SDK.