> 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](https://docs.tryterra.co/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.

## Connect your first wearable

{% stepper %}
{% step %}

### Choose your data sources

Go to **Connections** in the dashboard and, under **Sources**, enable the wearables and apps you want your users to connect. Enable the one you own for this test. Enabled sources are the ones your users can pick from.
{% endstep %}

{% step %}

### Choose where data goes

On the same page, under **Destinations**, add a **Webhook** and paste your webhook.site URL. Terra sends every user's data here as it becomes available. A webhook is the simplest destination; databases, cloud storage and queues are also supported.

{% 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.

**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 **Data generator** 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.

## Optional: Run 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 [Terra authentication widget](https://docs.tryterra.co/unified-api/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](https://docs.tryterra.co/destinations/webhooks.md) for handling payloads and verifying they came from Terra.

Keep your API key on your server, never in an app or web page.

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](https://docs.tryterra.co/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.
* [User authentication](https://docs.tryterra.co/unified-api/authentication-flow.md): open the widget from your own app.
* [Historical data requests](https://docs.tryterra.co/unified-api/requesting-historical-data.md): get data from before the user connected.
* [Mobile SDKs](https://docs.tryterra.co/mobile-sdks/mobile-only-sources.md): Apple Health, Samsung Health, and Health Connect need the mobile SDK.
