Withings integrationWithings API body composition and blood pressure, in your own cloud
Scales, blood pressure monitors and watches from Withings, connected through the official Public API and returned in the same schema as every other source. Self-hosted in your own cloud, under an MIT licence.
Built on Open Wearables
Data coverage
Withings data we support
Withings covers the measurements a watch cannot take, and everything below arrives in the same schema as the rest of your sources.
Body composition
Weight, fat, lean and muscle mass, water and bone.
Blood pressure
Systolic and diastolic, with heart rate alongside.
Vascular and metabolic
Pulse wave velocity, cardiovascular and metabolic age, VO2 max.
Vitals
SpO2, body and skin temperature, blood glucose.
Sleep
Stage timeline, efficiency, time in bed and naps.
Daily activity
Steps, distance, active and basal energy.
Workouts
Duration, heart rate range, steps, energy and distance.
Time series
Timestamped samples in the user's own time zone.
Measured, not imported
Activity other apps pushed into Withings is left out.
What working with Open Wearables gives you
Two views of the same deployment. One for the people wiring it in, one for the people signing it off.
One schema, including what a wrist cannot take
Scale and blood pressure readings arrive in the same shape as every other source, joined to the same user as their watch data, so your code carries no Withings-specific branches.
- Body composition
- Blood pressure
- One schema
Webhooks per user, nothing to register up front
Withings creates subscriptions with each user's own token rather than once for your application. Open Wearables subscribes every active connection, and every new one at connect time.
- Webhooks
- Per-user subscriptions
Local days that are actually local
Withings sends the user's time zone by name, not just an offset, so a daily total lands on the day they lived, daylight saving included, before the data reaches your schema.
- IANA time zones
- DST handled
Pull or push, switched from the dashboard
Polling works with nothing but OAuth, and tokens refresh before they expire. Webhooks are a setting rather than a rewrite, and switching back revokes the subscriptions cleanly.
- Polling
- Webhooks
- OAuth 2.0
Access you control
It runs in your cloud account, under your credentials. When we work on your system, we do it under a DPA you sign.
- Your credentials
- Your region
The Withings relationship stays yours
Credentials issued to your organisation, data going straight from Withings into your account.
- Your Withings app
- Your credentials
Costs you can see
Running it costs your own cloud bill, paid to your provider. Deployment and Integration are one-off services, and health scores and the other licensed modules come with Pro.
- Your cloud bill
- One-off services
No dependency on us
MIT licence, full source, public roadmap and public issues, plus community support on Discord.
- MIT license
- Full source
- Discord
How it works
From nothing to your first Withings query
- 01
Bring it up
Clone the repository and run it with Docker Compose. First API call in five minutes, before any provider is connected.
Terminal
git clone https://github.com/the-momentum/open-wearables.git cd open-wearables && docker compose up -d - 02
Create your Withings application
Register a Public API integration in the Withings Partner Hub and bring the client ID and secret. A free Withings account is enough to start, and the credentials stay in your name.
Withings Partner Hub - 03
Connect a user
Your user authorises through Withings' own consent screen. Open Wearables handles the flow and the token lifecycle, and subscribes their connection for notifications when webhooks are on.
- 04
Query the user, not the provider
Withings data arrives in the same schema as every other source, in your own database, so your application code carries no Withings-specific branches.
Withings API setup guide
The honest comparison
Hosted SaaS API, in-house build, or self-hosted
Where each one actually wins. If a hosted API fits your situation, use one.
| Hosted SaaS API | Build in-house | Open Wearables, self-hosted | |
|---|---|---|---|
| [01] Withings credentials | Theirs, already approved | Yours to obtain | Yours, in your own name |
| [02] Webhook subscriptions | They host them | Per-user work you build | Subscribed per user, handled for you |
| [03] Where Withings data sits | Their cloud, their regions | Yours | Your cloud account, your region |
| [04] The data model | Theirs, you build against their schema | Yours | Yours, in your database |
| [05] Time zone handling | Whatever they normalise to | Yours to get right | Local days resolved from the user's zone |
| [06] Withings API changes | They absorb them | Your team tracks and adapts | Fixed in a release you pull |
| [07] Cost shape | Scales with monthly active users | Salaries and infrastructure | Fixed, flattens as you grow |
What stays yours
The deployment, the data and what you build on it stay in your account, whoever runs it
Sovereignty
Withings data goes straight to your cloud, with no aggregator in between.
Residency
It stays in the region you chose, provable by pointing at an account.
Control
What you build on top of Open Wearables is yours, and the schema and the data are in your account.
Your own reasons
No regulator forcing it. You want the data in your own account anyway.
Withings is one integration in the same API
You query a user rather than a provider, so somebody who steps on a Withings scale in the morning and wears a different watch all day comes back in one shape. Adding either later does not change your code.
Deploy Open Wearables in your own cloud
The repository is public and the deployment is yours from the first commit. Start from the source, or bring us in to stand it up in your account with Withings connected and validated on real accounts.
FAQ
Do you have more questions?
Do we need our own Withings credentials?
Yes. You register a Public API integration in the Withings Partner Hub and bring the client ID and secret. A free Withings account is enough to create one, and the data relationship stays between you and Withings.
What does Withings give us that a watch does not?
Body composition and blood pressure. A scale measures fat mass, lean mass, water and bone, and a blood pressure monitor measures what no wrist device reports. Joined to the same user record as their watch data, that is a fuller picture than either source alone.
Does it support webhooks?
Yes, and Withings does them differently from everyone else. Subscriptions are created per user with that user's own token rather than once for your whole application, so there is no registration step blocking your first connection. Open Wearables subscribes each active connection, and anyone who connects later is subscribed automatically.
Can we start without webhooks?
Yes, polling is the default and needs nothing beyond OAuth, so you can have data flowing before you have a public callback. Withings limits an application with no webhook callback to ten linked users, though, so production runs with webhooks on. They are a switch in the dashboard, and switching back revokes the subscriptions cleanly.
What do we need before turning webhooks on?
A publicly reachable HTTPS callback on the standard port. Withings checks the endpoint before it creates any subscription, so it has to be live first. The setup guide in the docs covers the local development path.
How is sleep reported?
As the night's stage timeline, with minutes in deep, light, REM and awake, plus total duration, time in bed, efficiency and whether it was a nap. The night's lowest heart rate is kept as resting heart rate.
Which activity types does it recognise?
Withings' own categories, mapped to the same taxonomy your other providers use, so a swim from a Withings watch and a swim from another source group together in your queries.
Does it handle time zones properly?
Yes, and Withings makes that easier than most. It sends the time zone by name rather than as a bare offset, so a daily total can be placed on the day the user actually lived, including across daylight saving changes. That happens before the data reaches your schema.
Why is some of the user's activity missing?
A Withings account can hold daily activity that other apps pushed in. Those rows are left out, so the activity that lands in your schema came off a Withings device rather than being copied from elsewhere.
Can we combine Withings with other sources?
Yes, and it is one of the more useful combinations. Withings covers body composition and blood pressure, a watch or a ring covers activity and recovery, and you query the user rather than each provider.
We already have Withings credentials. What changes?
Very little. Bring the client ID and secret, point the deployment at your callback, and the connection flow works from there.