Quickstart

Create a sandbox user, verify authentication, and inspect the API's daily-data response in three requests.

4 min read Updated Sep 15, 2026

Prerequisites

A Sonar organization with access to the Developers workspace
A sandbox API key created in Developers → API keys
curl, Python, or a server-side JavaScript runtime

Keep the key on your server

API keys can create and delete users and access their health data. Do not put one in browser or mobile application code.

Set the key once in your server-side environment. Every example below reads from the same variable.

bash

export SONAR_API_KEY="sonar_v1_test_..."

Make Your First Calls

Create a User

Use a stable ID from your own system as external_ref. Set display_name to the editable label coaches should see in Atlas. The optional profile helps provider routing and score calculations.

python

import os

import requests

BASE = "https://atlas.sonarhealth.co/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SONAR_API_KEY']}"}

response = requests.post(
    f"{BASE}/users",
    headers=HEADERS,
    json={
        "external_ref": "member_123",
        "display_name": "Jordan Kim",
        "profile": {"timezone": "Europe/Madrid"},
    },
)
response.raise_for_status()
user = response.json()
print(user["id"])

typescript

const base = "https://atlas.sonarhealth.co/v1";
const headers = {
  Authorization: `Bearer ${process.env.SONAR_API_KEY}`,
  "Content-Type": "application/json",
};

const response = await fetch(`${base}/users`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    external_ref: "member_123",
    display_name: "Jordan Kim",
    profile: { timezone: "Europe/Madrid" },
  }),
});
if (!response.ok) throw new Error(await response.text());
const user = await response.json();
console.log(user.id);

json

{
  "id": "7e4e91a5-1e4f-4fc2-903c-251046d2a4d3",
  "external_ref": "member_123",
  "display_name": "Jordan Kim",
  "created_at": "2026-09-09T09:30:00.000Z"
}

Successful creation returns 201 Created. The response is the user object itself; there is no outer data envelope.

Verify the User

Use the returned id to confirm that the user is available to later connection and data requests.

bash

curl "https://atlas.sonarhealth.co/v1/users/7e4e91a5-1e4f-4fc2-903c-251046d2a4d3" \
  -H "Authorization: Bearer $SONAR_API_KEY"

The response has the same id, external_ref, display_name, and created_at fields as creation.

Inspect Daily Data

The daily endpoint already has its final response shape, even before this user has a connected data source.

bash

curl "https://atlas.sonarhealth.co/v1/users/7e4e91a5-1e4f-4fc2-903c-251046d2a4d3/daily?types=steps,resting_heart_rate&from_date=2026-09-01&to_date=2026-09-03" \
  -H "Authorization: Bearer $SONAR_API_KEY"

json

{
  "from_date": "2026-09-01",
  "to_date": "2026-09-03",
  "dates": ["2026-09-01", "2026-09-02", "2026-09-03"],
  "series": { "steps": [null, null, null], "resting_heart_rate": [null, null, null] }
}

New users have no synthetic data. Values remain null until a connected provider has synced and Sonar has processed the data.

Connect Real Data

Your server integration is now verified. Next, connect a cloud wearable or add a mobile SDK. After the first synchronization, query the same endpoints to read the user’s normalized health data.