FAQ

What is Sonar? Sonar is a Backend as a Service for wearable health data. It handles device connectivity, data normalization and health scoring — so you can focus on your product instead of health data infrastructure.

What devices does Sonar support? Apple Health (iOS), Health Connect (Android), Samsung Health, and 60+ cloud-connected wearable devices — including Garmin, Fitbit, Oura, Whoop, Polar, COROS, Suunto, and more. See Device Connectivity for the full compatibility matrix.

How is Sonar different from Apple HealthKit or Health Connect directly? HealthKit and Health Connect are on-device health stores — they collect and store data locally. Sonar is a backend service that ingests data from those stores (via our mobile SDKs) plus cloud-connected wearables, normalizes everything into a consistent format, computes health scores, and serves it through a REST API your backend can query. You'd need HealthKit/Health Connect and Sonar — not one or the other.

Can I use Sonar without a mobile app? Yes, partially. If your users connect cloud-based wearables (Garmin, Fitbit, Oura, etc.), the REST API handles everything server-side — no mobile SDK needed. The Mobile SDK is only required for on-device sources like Apple Health, Health Connect, and Samsung Health.

Does Sonar store any personally identifiable information (PII)? No. Sonar stores health data, not identity data. You link your users to Sonar via a reference_id (your internal user ID), and Sonar never asks for names, emails, or other PII. See User Model for details.

Which token type should I use? It depends on where the request originates. Use an API Key for server-to-server calls (creating users, querying any user's data, managing webhooks). Use a User Token for client-side reads (frontends, mobile apps querying health data directly). Use a Mobile Token only for initializing the Mobile SDK. See Authentication for the full decision tree.

Can I call the API directly from my mobile or web app? Yes — use a User Token. Your backend generates a User Token scoped to a single user, passes it to the client, and the client uses it as a Bearer token for read-only API access. This avoids proxying every request through your backend. Never use your API Key client-side. See Authentication — User Token.

How long do tokens last? API Keys last 90 days and should be rotated before expiry. User Tokens expire after 1 hour and can be refreshed from your backend. Mobile Tokens expire in 5 minutes and are single-use — generate a fresh one each time your app needs to initialize the SDK. See Authentication for lifecycle details.

What happens if a token expires mid-session? The API returns 401 with error token_expired. For User Tokens, have your client send the expired token to your backend, which refreshes it and returns a new one. For Mobile Tokens, generate a fresh one and reinitialize the SDK. API Keys that are past their 90-day rotation window are automatically revoked.

How do devices connect to Sonar? Through two paths: the Mobile SDK reads data from on-device health stores (Apple Health, Health Connect, Samsung Health), while cloud-connected devices (Garmin, Fitbit, Oura, etc.) connect via their manufacturer's API. See Device Connectivity for details on each path.

What happens if a user has multiple devices? Sonar deduplicates overlapping data at the metric level — each metric is resolved independently using priority rules. For example, ring sensors take priority for sleep data, while wrist-worn devices are preferred for heart rate. See Data Model — Multi-Device Deduplication for the full priority rules.

Does connecting the same device via both SDK and Cloud API cause problems? No. Sonar detects overlapping sources and deduplicates automatically. However, for predictable sync behavior, pick one connection path per device type. The Mobile SDK path is recommended when available — it provides faster sync and works offline.

A device I need isn't listed. Can you add it? If the device writes to Apple Health or Health Connect, it already works through the Mobile SDK — no integration needed. For cloud-connected devices not yet supported, reach out to your account contact. New integrations are added regularly based on demand.

How do I know which devices a user has connected? Query GET /v1/users/{user_id}/devices. Each device includes id, provider, status, connected_at, and last_sync_at.

Can users disconnect a device? Yes. Use the device teardown API to disconnect a device and remove its data. The Sonar platform handles deauthorization with the device provider automatically.

How quickly does data sync? Apple Health and Health Connect data arrives within seconds to minutes of a device sync. Cloud-connected wearables typically sync within 5–15 minutes, depending on the manufacturer's push cadence. See Data Model — Data Freshness for details.

What format is the data in? All data is returned as JSON via the REST API. Metrics are normalized to metric units (km, kg, °C) regardless of the source device. You can request imperial units per-request by passing unit_system=imperial. See API Conventions for details.

What happens if I query data before a device has synced? The API returns an empty data array — no error. Check last_sync_at on the user object or subscribe to data.updated webhooks to know when data is available. See Data Delivery for webhook setup.

Can I backfill historical data? Cloud-connected devices automatically backfill historical data when first connected — the amount varies by provider (typically 1–6 months). Mobile SDK connections sync whatever is available in the on-device health store, up to 2 years back. Scores are computed retroactively once enough backfilled data is available.

How do I query data for a large date range? The /daily endpoint handles ranges up to 90 days in a single request. For longer ranges, paginate by splitting into 90-day windows. Timeseries data (intraday samples) should be queried in smaller windows — 7 days is a practical maximum per request.

Can I get raw data instead of canonical? Not through the REST API — Sonar intentionally exposes only the canonical (deduplicated) layer. If you need to see which device contributed a specific value, use include_sources=true on any query to see the source device and original value.

What are the available metric IDs? Sonar normalizes data into 70+ metrics across seven categories: activity, sleep, vitals, body composition, energy, nutrition, and scores. The Data Catalog is the complete reference — every metric_id, unit, and description.

Why is there missing data for some days? Missing data typically means the user didn't wear their device or the device didn't sync that day. Sonar returns data for days where it exists and omits days with no data — it never fabricates values. Check last_sync_at on the user or device to see when data last arrived. Health scores adjust their internal weighting when some inputs are missing rather than returning nothing.

Should I use webhooks, the Events API, or both? Use both. Webhooks give you real-time push notifications (within seconds) so you can update UIs immediately. The Events API gives you a durable, cursor-based event log you can poll to catch anything your webhook handler might have missed during deployments or network blips. See Data Delivery for the recommended pattern.

How do I know when new data is available for a user? Subscribe to data.updated webhooks for real-time notifications, or poll the Events API with a cursor. Both tell you what changed (which metrics or scores) and for whom (user ID) — you then query the REST API to fetch the actual values. See Data Delivery — Event Types.

What event types are available? Four types: data.updated (new health data synced), score.updated (scores recomputed), device.connected (user connected a new device), and device.disconnected (user disconnected a device). Each event is a notification — query the REST API for the actual data.

What happens if my webhook endpoint is down? Sonar retries with exponential backoff — up to 8 attempts over approximately 24 hours. If all retries fail, the event stays in the Events API log. This is why running a periodic Events API poll alongside webhooks is recommended as a safety net.

What health scores does Sonar compute? Eight scores on a 0–100 scale: Recovery, Strain, Sleep, Stress, Inactive Stress, Sleep Stress, Energy Reserve, and Nutrition. Each score includes a factors array explaining which inputs contributed and how. See Health Scores for details.

How long until scores are ready? Scores start computing after 24 hours of data. The score_status field on the user object transitions from calibrating to ready — this typically takes 3–4 days. Full personalization (rolling baselines for sickness detection, sleep vitals comparison, etc.) reaches accuracy after about 4 weeks.

Why are my user's scores empty or showing "calibrating"? The user hasn't accumulated enough data yet. Check the score_status field on the user object — calibrating means less than 3–4 days of data. Show your users a "Setting up your baseline…" message during this period. Once score_status transitions to ready, scores are available via the API. If score_status is stale, the user hasn't synced in 7+ days.

What data does each score need? Recovery needs sleep + overnight heart rate or HRV. Strain needs heart rate. Sleep needs a sleep session with duration. Stress needs heart rate or HRV. Energy Reserve needs vitals + sleep history. Nutrition needs at least one macronutrient or caloric entry from a connected app. See Health Scores — Data Requirements for the full matrix.

What happens when a user switches devices? The canonical layer handles it automatically. New data comes from the new device and deduplication rules apply as usual. Historical data from the old device remains queryable. Scores recalibrate based on the new data source within a few days.

Should I cache scores or query them fresh? Scores update at most a few times per day (after syncs and consolidation). For dashboard UIs, querying on page load is fine. For high-traffic endpoints, cache scores for 5–15 minutes or subscribe to score.updated webhooks and invalidate your cache on each event.

Can scores go down when more data arrives? Yes. Scores always reflect the latest full picture. A mid-day strain score might change as afternoon activity comes in, and Recovery will drop if overnight vitals indicate poor autonomic recovery — even if sleep duration was adequate.

What is reference_id and how should I use it? reference_id is the bridge between your identity system and Sonar. Pass your internal user ID (UUID, integer, or any stable string) when creating a Sonar user. Every API response includes both your reference_id and Sonar's id, so you never need to maintain a separate mapping table. You can also look up users by reference_id via GET /v1/users?reference_id=your-internal-id.

What happens when I delete a user? Deletion is permanent and irreversible. It disconnects all linked devices, de-authorizes them with the wearable provider, stops all syncing, and permanently deletes all associated health data and computed scores. If the user returns, create a new Sonar user — they'll need to reconnect their device and go through the calibration period again. See User Model — Deleting a User.

How do I create a user in Sonar? POST /v1/users with a reference_id (your internal user ID) and optionally a timezone (IANA format, used for score computation windows). Sonar returns a user object with an id you'll use for all subsequent API calls. See the Quickstart for code examples.

How do I test without a real wearable device? Use the sandbox environment. Every user created with a sandbox API key (sk_sandbox_...) is automatically seeded with 7 days of realistic wearable data and pre-computed health scores — no device connection required. This lets you build and test your integration end-to-end before going live.

What's the difference between sandbox and production? Sandbox uses sk_sandbox_ API keys, auto-seeds test data, and is free. Production uses sk_live_ API keys, connects to real devices, and is billed. The API surface is identical — code that works in sandbox works in production with no changes. See the Quickstart to get started with sandbox.

Where is health data stored? All health data is stored in AWS infrastructure in encrypted storage. Data is encrypted at rest (AES-256) and in transit (TLS 1.2+).

How is user data isolated? Every data operation is scoped by a unique user identifier. There is no cross-user data access at any layer — database queries, S3 storage paths, and API responses are all isolated per user.

Can users delete their data? Yes. The device teardown API removes all stored health data for a user's device, including raw files and consolidated data. Full user deletion removes all data across all connected devices. See User Model — Deleting a User.

Is Sonar HIPAA compliant? Contact your account representative for details on HIPAA compliance, BAA availability, and other regulatory requirements for your use case.

What are the API rate limits? 100 requests per second per API key, with bursts up to 200 for short spikes. If you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header. For high-volume use cases, use webhooks to react to changes instead of polling per-user endpoints. See API Conventions for full details.

Are API requests idempotent? All GET requests are safe to retry. POST requests to create resources (users, webhooks) are not idempotent — calling them twice creates two resources. Use reference_id on user creation to detect duplicates in your system. Token generation endpoints are idempotent in the sense that calling them twice issues two valid tokens, which is harmless.

How should I handle retries? Use exponential backoff with jitter. Start at 1 second, double on each retry, cap at 30 seconds, and add random jitter. Always respect the Retry-After header on 429 responses. For 500 errors, retry up to 3 times — if it persists, the issue is on Sonar's side.

Which platforms are supported? iOS (Swift), Android (Kotlin), and React Native (with separate modules for Apple Health and Android/Health Connect). See the SDK Overview for all available packages.

Do I need the Mobile SDK? Only if you want to collect data from on-device health stores (Apple Health, Health Connect, Samsung Health). If your users only connect cloud-based wearables, the REST API alone is sufficient.

Does Sonar work with Expo? Yes. The React Native packages include Expo config plugins. Add @sonar-health/react-native-apple-health and/or @sonar-health/react-native-android to your app.json plugins array, and the native configuration (capabilities, permissions, manifest entries) is handled automatically. See React Native SDK for the full Expo setup.

How does the SDK handle background sync? The SDK registers for background delivery with the OS health store. On iOS, HealthKit wakes your app when new data is available. On Android, the SDK uses WorkManager to schedule periodic syncs with Health Connect. Data is pushed to Sonar's servers automatically — no polling required from your app.

What permissions does the SDK request? The SDK requests read-only access to health data categories. You configure which categories to request in the SDK initialization. Users see a standard OS permission dialog (Apple Health or Health Connect) and can grant or deny individual data types.