Wearable API Integration Guide

Overview

This guide walks you through the complete flow of integrating Open Wearables with your application, from creating a user to fetching their health data.

Create a user in Open Wearables
Connect user to a wearable provider (Garmin, Polar, Suunto)
Sync data from the provider
Fetch timeseries, workouts, or sleep data

Step 1: Create a User

First, create a user in Open Wearables to represent your application’s user.

curl -X POST "http://localhost:8000/api/v1/users" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "external_user_id": "your-app-user-123"
  }'

Use external_user_id to map Open Wearables users to your application’s user IDs for easy lookup later.

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-12-19T10:30:00Z",
  "first_name": null,
  "last_name": null,
  "email": "user@example.com",
  "external_user_id": "your-app-user-123"
}

Save the id - you’ll need it for all subsequent API calls.

Open Wearables allows duplicate email addresses. If you need uniqueness, check for existing users first using GET /api/v1/users?search=user@example.com which returns a paginated list.

Step 2: Connect to a Provider

Initiate OAuth to connect the user to their wearable provider.

curl -X GET "http://localhost:8000/api/v1/oauth/garmin/authorize?user_id=550e8400-e29b-41d4-a716-446655440000&redirect_uri=https://yourapp.com/connected" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Response:

{
  "authorization_url": "https://connect.garmin.com/oauthConfirm?oauth_token=...",
  "state": "abc123..."
}

Redirect the user to authorization_url. After they authorize, they’ll be redirected back to your redirect_uri.

Provider names must be lowercase: garmin, polar, suunto, apple

Frontend Example

// Get OAuth URL
const response = await fetch(
  `${API_URL}/api/v1/oauth/garmin/authorize?user_id=${userId}&redirect_uri=${encodeURIComponent(callbackUrl)}`,
  { headers: { 'X-Open-Wearables-API-Key': API_KEY } }
);
const { authorization_url } = await response.json();

// Redirect user to provider
window.location.href = authorization_url;

Step 3: Sync Data

After OAuth completes, an initial sync is triggered automatically. For subsequent syncs or to fetch historical data:

# Garmin - with time range (recommended)
curl -X POST "http://localhost:8000/api/v1/providers/garmin/users/550e8400-e29b-41d4-a716-446655440000/sync?summary_start_time=2025-01-01T00:00:00Z&summary_end_time=2025-01-31T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

# Suunto/Polar - no time range required
curl -X POST "http://localhost:8000/api/v1/providers/polar/users/550e8400-e29b-41d4-a716-446655440000/sync" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

For Garmin, including summary_start_time and summary_end_time is recommended to specify the date range for data retrieval.

Step 4: Fetch Data

Now you can fetch the user’s health data.

Timeseries Data (Heart Rate, Steps, etc.)

curl -X GET "http://localhost:8000/api/v1/users/550e8400-e29b-41d4-a716-446655440000/timeseries?start_time=2025-01-01T00:00:00Z&end_time=2025-01-31T00:00:00Z&types=heart_rate&types=steps" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Workouts

curl -X GET "http://localhost:8000/api/v1/users/550e8400-e29b-41d4-a716-446655440000/events/workouts?start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Sleep Sessions

curl -X GET "http://localhost:8000/api/v1/users/550e8400-e29b-41d4-a716-446655440000/events/sleep?start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Menstrual Cycles

curl -X GET "http://localhost:8000/api/v1/users/550e8400-e29b-41d4-a716-446655440000/events/menstrual-cycles?start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Complete JavaScript Example

const API_URL = 'http://localhost:8000';
const API_KEY = 'your-api-key';

async function integrateUser(email, externalId) {
  // 1. Create user
  const userRes = await fetch(`${API_URL}/api/v1/users`, {
    method: 'POST',
    headers: {
      'X-Open-Wearables-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email, external_user_id: externalId })
  });
  const user = await userRes.json();

  // 2. Get OAuth URL for Garmin
  const authRes = await fetch(
    `${API_URL}/api/v1/oauth/garmin/authorize?user_id=${user.id}&redirect_uri=${encodeURIComponent(window.location.origin + '/connected')}`,
    { headers: { 'X-Open-Wearables-API-Key': API_KEY } }
  );
  const { authorization_url } = await authRes.json();

  // 3. Redirect user to provider
  window.location.href = authorization_url;
}

async function fetchUserData(userId) {
  // After OAuth callback, fetch data
  const now = new Date().toISOString();
  const monthAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();

  const response = await fetch(
    `${API_URL}/api/v1/users/${userId}/timeseries?start_time=${monthAgo}&end_time=${now}&types=heart_rate`,
    { headers: { 'X-Open-Wearables-API-Key': API_KEY } }
  );
  return response.json();
}

Overview

Integration Guides

Authentication

Users

Connections

Providers

Data Sync

Summaries

Timeseries

Events

Health Scores

Data Sources

Meta

Apple Health Import

Mobile SDK

Webhooks

Sync Status

Wearable API Integration Guide

Overview

Step 1: Create a User

Step 2: Connect to a Provider

Frontend Example

Step 3: Sync Data

Step 4: Fetch Data

Timeseries Data (Heart Rate, Steps, etc.)

Workouts

Sleep Sessions

Menstrual Cycles

Complete JavaScript Example

Next Steps

Provider Setup

Data Types

​Overview

​Step 1: Create a User

​Step 2: Connect to a Provider

​Frontend Example

​Step 3: Sync Data

​Step 4: Fetch Data

​Timeseries Data (Heart Rate, Steps, etc.)

​Workouts

​Sleep Sessions

​Menstrual Cycles

​Complete JavaScript Example

​Next Steps

Provider Setup

Data Types

Overview

Step 1: Create a User

Step 2: Connect to a Provider

Frontend Example

Step 3: Sync Data

Step 4: Fetch Data

Timeseries Data (Heart Rate, Steps, etc.)

Workouts

Sleep Sessions

Menstrual Cycles

Complete JavaScript Example

Next Steps