Samsung Health API integration guide for Android developers

Open Wearables Team · June 6, 2026 · 4 min read

Key Takeaways

The Samsung Health API is not a cloud REST API. It is a device-side SDK that reads data stored locally on Samsung devices.
Samsung Health and Health Connect solve similar problems but cover different device populations. Use Samsung Health ("samsung") for Samsung-specific deployments, and Health Connect ("google") for broader Android 10+ coverage.
Open Wearables Android SDK handles the Samsung Health SDK connection, permission flow, background sync scheduling, token management, and data normalization.
Samsung Health coverage includes 20+ data types: steps, heart rate, HRV, SpO2, blood pressure, blood glucose, energy expenditure, body composition, temperature, workouts, and sleep.
Background sync is WorkManager-backed, surviving app restarts and respecting battery optimization.
Samsung Health is only available on Samsung devices. For non-Samsung Android devices, use the Health Connect provider.
The SDK requires Android 10 (API 29+), compile SDK 36, Kotlin 2.1.0+.

The Core Problem: Samsung Health Is Not a Cloud API

When developers first look for a Samsung Health API, they often expect something similar to other health platforms: an OAuth flow, a set of REST endpoints, a way to pull data server-side. Samsung Health does not work that way.

Samsung Health stores data locally on the device. Access happens through the Samsung Health SDK, which communicates with the Samsung Health app via a local IPC connection. There is no cloud endpoint you can call. Your code needs to run on the device, with the user's explicit permission, and the Samsung Health app must be installed.

This creates a specific integration pattern: you ship native Android code, that code syncs data to your backend, your backend reads the normalized data through your API. Every piece of complexity lives in step one. Open Wearables handles that entire step.

Samsung Health vs Health Connect: Which One to Use

Health Connect works on any Android 10+ device and covers 30+ data types. Provider ID in Open Wearables: "google".

Samsung Health works on Samsung devices only, covers 20+ data types. Provider ID: "samsung".

For most apps targeting a broad Android audience, Health Connect is the more practical starting point. Samsung Health makes sense when your user base is Samsung-specific. Open Wearables supports both through a unified interface.

What Open Wearables Android SDK Does for You

Without Open Wearables, Samsung Health API integration involves: adding the Samsung Health SDK, setting up the connection, handling connection state, building per-type permission flows, writing WorkManager background sync, normalizing Samsung-specific formats, implementing token refresh, and storing credentials securely.

With Open Wearables, you add one dependency, generate a backend token, and call three SDK methods.

Backend Setup: Generating a User Token

            POST /api/v1/users/{user_id}/token
X-Open-Wearables-API-Key: your_api_key

Returns access_token and refresh_token. Pass these to the Android client. Never embed app_id or app_secret in the mobile app.

Android SDK: Installation and Setup

Add the dependency:

            // settings.gradle.kts
maven { url = uri("https://jitpack.io") }

// build.gradle.kts
implementation("com.github.the-momentum:open-wearables-android-sdk:0.5.0")

Requirements: minSdk = 29, compileSdk = 36, Kotlin 2.1.0+.

Initialize in Application class:

            OpenWearables.init(context = this, baseUrl = "https://your-backend.com")

Sign in and request Samsung Health permissions:

            sdk.signIn(accessToken = accessToken, refreshToken = refreshToken, userId = "user_123")

sdk.requestAuthorization(
    activity = this,
    provider = "samsung",
    dataTypes = listOf("steps", "heart_rate", "hrv", "oxygen_saturation", "workout", "sleep")
)

Start background sync:

            sdk.startBackgroundSync(provider = "samsung", syncDaysBack = 7)

Reading Data From Your Backend

            GET /api/v1/users/{user_id}/timeseries
GET /api/v1/users/{user_id}/events/workouts
GET /api/v1/users/{user_id}/events/sleep

All timestamps are UTC. Units are canonical. Data from Samsung Health and Health Connect look identical in the response.

Limitations

Samsung Health is Samsung devices only. The SDK will not connect to Samsung Health on non-Samsung Android devices.

The Samsung Health app must be installed and up to date. Older versions expose fewer data types.

Quickstart

            git clone https://github.com/the-momentum/open-wearables
cd open-wearables
docker compose up -d

API at http://localhost:8000. Auth via X-Open-Wearables-API-Key. MIT license, $0 per user.

Note: Samsung Health requires a physical Samsung device. The SDK does not work on emulators.

See Related Articles

FAQ

Is there an official Samsung Health REST API I can call from my server?

No. Samsung Health does not expose a cloud API for third-party developers. Data access goes through the Samsung Health SDK on the device.

What happens if the user has both Samsung Health and Health Connect installed?

You can request authorization from both providers independently. The SDK treats "samsung" and "google" as separate data sources. If the user connects both, your backend may receive overlapping data for the same time window.

Does Open Wearables work on non-Samsung Android devices?

The Open Wearables Android SDK works on any Android 10+ device. Samsung Health specifically requires a Samsung device. On non-Samsung devices, use the "google" provider for Health Connect.

How does automatic token refresh work?

The SDK catches 401 responses, uses the stored refresh token to call the token endpoint, updates EncryptedSharedPreferences with the new token pair, and retries the failed request. This happens transparently.

How far back can I backfill Samsung Health data?

The syncDaysBack parameter in startBackgroundSync() controls the historical backfill depth. A value between 7 and 30 days is a reasonable starting point.

Back to all posts