User Model

A Sonar user is the data container for one end-user in your system. Every device connection, health metric, and computed score belongs to exactly one Sonar user. When you add Sonar to your product, you create a Sonar user for each of your users who will connect a wearable.

Identity and Isolation

Sonar does not own your users' identities — you do. Sonar provides data isolation between your end-users under your account.

The reference_id is the bridge between your identity system and Sonar. Use your internal user ID — UUID, integer, or any stable string. Sonar stores it opaquely and never asks for names, emails, or other PII. Every API response includes both your reference_id and Sonar's id, so you never need to maintain a mapping table.

Creating a User

import requests

user = requests.post(
    "https://api.sonarhealth.co/v1/users",
    headers={"Authorization": "Bearer sk_live_abc123"},
    json={
        "reference_id": "your-internal-id",
        "timezone": "America/New_York",  # used for score computation timing
    },
).json()["data"]

const { data: user } = await fetch("https://api.sonarhealth.co/v1/users", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_abc123",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reference_id: "your-internal-id",
    timezone: "America/New_York",
  }),
}).then(r => r.json());

{
  "data": {
    "id": "usr_abc123",
    "reference_id": "your-internal-id",
    "timezone": "America/New_York",
    "status": "active",
    "score_status": "calibrating",
    "last_sync_at": null,
    "last_score_at": null,
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Key Fields

Score Status

Scores require a baseline period before they're meaningful. Use score_status to communicate state to your users:

Managing Users

You can look up, update, and list users through the API. For example, you can find a Sonar user by their reference_id without storing the Sonar id:

GET /v1/users?reference_id=your-internal-id

See API Conventions for general API patterns.

Deleting a User

Deleting a user disconnects all linked devices, de-authorizes them with the wearable provider, stops all syncing, and permanently deletes all associated data.

requests.delete(
    f"https://api.sonarhealth.co/v1/users/{user_id}",
    headers={"Authorization": "Bearer sk_live_abc123"},
)

await fetch(`https://api.sonarhealth.co/v1/users/${userId}`, {
  method: "DELETE",
  headers: { Authorization: "Bearer sk_live_abc123" },
});

If a deleted user returns, create a new Sonar user — they will need to reconnect their device and go through the calibration period again.

Mobile Tokens

Your mobile app never uses your API key directly. Instead, your backend generates a short-lived mobile token scoped to a single user and passes it to the SDK at initialization time. Tokens are single-use and expire in 5 minutes.

See the SDK documentation for the full initialization flow.