--- title: "How to Integrate the Withings API (2026)" canonical: "https://aifitnessapi.com/integrate/withings-api" cluster: "Integration Guides" primary_query: "withings api" last_reviewed: "2026-10-17" description: "Integrate the Withings Public API: OAuth with signed requests, 3-hour tokens, getmeas and lastupdate sync, notifications, limits and the Withings+ rule." publisher: "AIFitnessAPI — independent, not sponsored" cite_as: "\"How to Integrate the Withings API (2026)\", AIFitnessAPI, https://aifitnessapi.com/integrate/withings-api" --- # How to Integrate the Withings API (2026) > The Withings Public API gives your app the measurements from a user's Withings scales, blood pressure monitors, sleep sensors and trackers after they authorize you over OAuth 2.0. Setup is free with no prerequisites: create an application, send users to Withings' authorization URL, exchange the code within 30 seconds using a signed requesttoken call, then fetch data with getmeas and the other services, ideally after Withings notifies your callback URL. Access tokens last 3 hours, the standard API allows 120 requests per minute per application, and Withings announced that from October 12, 2026 newly created accounts would need Withings+ to share data with a free-plan app, a notice that was gone from its developer home page by October 22, 2026. - Canonical: https://aifitnessapi.com/integrate/withings-api - Last reviewed: 2026-10-17 - Publisher: AIFitnessAPI (https://aifitnessapi.com) — independent, not sponsored - Cite as: "How to Integrate the Withings API (2026)", AIFitnessAPI, https://aifitnessapi.com/integrate/withings-api --- Withings makes scales, blood pressure monitors, sleep sensors, trackers and thermometers, and its cloud API returns what those devices measure. This guide covers the **Public API**, which Withings describes as "designed for individuals and partners without a formal contract", from Withings' developer site as read on October 17, 2026. Withings' other solutions (Cellular, Withings RPM and Logistics Services) are out of scope here. One change dominates 2026 planning. Withings' developer home page, as the Internet Archive captured it on October 16, 2026, said Withings+ becomes required on the Start for Free API plan from October 12, 2026: Withings accounts created after that date need a membership to share health data with a free-plan app, including apps that are already live. Accounts created before that date are unaffected, and Withings said Enterprise lifts the requirement for specific use cases. That notice was no longer on the home page when we read it on October 22, 2026, and Withings' plans page did not render for us, so we could not confirm whether the requirement still stands; ask Withings before you plan around it. If you are still choosing a provider, start with [wearable data APIs](/fitness-apis/wearable-data-apis). ## Access and approval | Question | What Withings' pages say | |---|---| | What does it cost to start? | "There are no prerequisites, and free access is provided" on the EU Medical Cloud | | Is there a review? | None is described for the Public API: you create an application and get a `client_id` and `client_secret` | | What do users need? | A Withings device set up in the Withings app; Withings announced that from October 12, 2026 new accounts need Withings+ to share with a free-plan app (see above) | | Any limits on a new app? | An app whose callback URL misses Withings' requirements stays in restricted mode, limited to 10 linked users | | Where does data live? | The EU Medical Cloud in France by default; a US Medical Cloud for HIPAA-covered entities, by request | Withings recommends creating the developer account with a shared professional email rather than a personal Withings account. Its developer dashboard has teams with three roles: Admin, Developer and Support Agent, and only an Admin can manage production applications. The cloud is fixed for good: Withings says your cloud is set when your access contract is created and cannot be switched afterwards. ## Auth and scopes Withings uses OAuth 2.0 with the authorization-code flow. Send the user to its authorization URL: ```http GET https://account.withings.com/oauth2_user/authorize2 ?response_type=code &client_id=YOUR_CLIENT_ID &scope=user.info,user.metrics,user.activity &redirect_uri=https://yourapp.example.com/callback &state=RANDOM_ANTI_CSRF_STRING ``` Scopes are comma-separated: | Scope | What Withings says it allows | |---|---| | `user.activity` | Physical activity and sleep data; also required for notification management | | `user.metrics` | Health measurements, heart recordings, stethoscope data and goals; also required for notification management | | `user.info` | Account information, linked devices and goals, and device linking | | `user.sleepevents` | Notifications when sleep events happen: bed in, bed out, inflate done | Two details are unusual. First, **the authorization code is only valid for 30 seconds**, so exchange it in the callback handler, not in a queue. Second, **Withings signs some requests**: you call `getnonce` on the signature service with an HMAC SHA-256 signature keyed by your client secret, then sign the token request with that nonce. The exchange itself is the `requesttoken` action on `https://wbsapi.withings.net/v2/oauth2`, sent with your `client_id`, `redirect_uri`, the `code`, `grant_type=authorization_code`, the nonce and the signature. Token lifetimes are short at the front and long at the back: | Token | Lifetime Withings documents | |---|---| | `access_token` | 3 hours | | `refresh_token` | 1 year | | The previous `refresh_token` | 8 hours after a new one is issued, or once the new access token is used | Every refresh returns a new refresh token, and Withings warns that failing to store it can lose you access once the old one expires. For testing, add `mode=demo` to the authorization request to log in as Withings' demo user. ## Data: measures, activity, sleep and heart Withings says that once a user authorizes your application, "you will have access not only to new data but also to all historical health data collected by the devices", so a new connection can backfill the user's history. Calls are `POST` requests to `https://wbsapi.withings.net` services with an `action` parameter: | Service and action | Returns | |---|---| | Measure `getmeas` | Measures by `meastype`, for example weight (1), fat ratio (6) and bone mass (88); blood pressure, SpO2, temperature, glucose and more | | Measure v2 `getactivity`, `getintradayactivity`, `getworkouts` | Daily activity, intraday activity and workouts | | Sleep v2 `get`, `getsummary` | Sleep data and nightly summaries | | Heart v2 `list`, `get` | ECG recordings | | User v2 `getdevice` | The user's linked devices | ```bash curl -s -X POST "https://wbsapi.withings.net/measure" \ -H "Authorization: Bearer USER_ACCESS_TOKEN" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "action=getmeas" \ -d "meastypes=1,6,88" \ -d "lastupdate=1760000000" ``` Use `lastupdate` for ongoing sync: Withings says it returns everything created or modified since that timestamp, including updates you missed if a notification was lost. Withings' catalogue lists 96 biomarkers across 9 device families, and marks some as requiring the Advanced Biomarkers plan, so check the catalogue before you promise a metric. ## Webhooks: data notifications Withings pushes notifications rather than data. Subscribe a callback URL to a category (`appli`) with the `subscribe` action on the notify service, using the user's access token. Categories include 1 (weight and body composition), 4 (blood pressure and heart rate), 16 (activity), 44 (sleep summary) and 54 (ECG); the notification carries `userid`, `appli` and a `startdate` and `enddate` window, and you fetch the data yourself. Withings' rules for the callback URL are strict: - HTTPS only, a domain name rather than an IP address or localhost, ports 80 or 443 only, and at most 255 characters. - It must answer HTTP `HEAD` with a 2xx, because Withings checks the URL before registering it. - A URL that misses these leaves the app in restricted mode, limited to 10 linked users, which Withings intends for development only. Reliability is documented in detail. If your endpoint does not answer with a status below 400, Withings retries on a schedule of 10 seconds, 1 minute, 1 hour and 4 hours, two attempts per cycle and 10 in total. After 4 failed notifications in a row it sends a warning email for each, and after 20 days of unresolved failures it cancels the subscription. Missed notifications are not redelivered, so backfill with `lastupdate` once you are back. Typical delivery is under 2 minutes, with no real-time commitment on the standard plan. To secure the endpoint, Withings publishes its notification IP ranges as DNS TXT records (`ipblock-notify.withings.net` for the EU cloud) and suggests adding a secret query parameter to the callback URL that you check on every request. ## Rate limits Withings says the standard API enforces a limit of 120 requests per minute across your application, and that polling hits it quickly, which is why it points everyone to notifications. The Enterprise plan unlocks higher limits and dedicated support; Withings' plans page did not render for us, so this guide does not quote its prices. ## What changed recently | When | Change (Withings' pages) | |---|---| | October 12, 2026 | Withings+ required on the Start for Free API plan for accounts created after that date, including for apps already live, per a home-page notice captured October 16, 2026 and gone by October 22, 2026 | | Standing policy | Major changes get one month's notice, up to three months for business-critical ones; emergency changes up to two weeks or none; normal changes without notice | Withings publishes breaking changes and deprecations on a developer updates portal and a mailing list, and adds the contact email of every developer application to that list automatically. ## Gotchas and production notes - **The 30-second code.** Exchange the authorization code immediately; a slow callback fails silently from the user's point of view. - **Sign before you ask.** Token requests need a fresh nonce and an HMAC signature; every request needs a new nonce. - **Store the newest refresh token every time.** The previous one dies 8 hours after a new one is issued. - **Budget for Withings+.** Withings announced that users who create a Withings account after October 12, 2026 need a membership to share data with a free-plan app; confirm it still applies, since the notice had left the developer home page by October 22, 2026. - **Pick the cloud once.** EU or US is fixed when your access contract is created. - **Notifications are pointers.** Fetch the data after each notification, answer within a few seconds, and reconcile with `lastupdate` after any outage. The `withings-api` Python package is reviewed at [withings-api](/libraries/withings-api). The rest of the cluster is at [how to integrate a fitness or health API](/integrate). ## Sources - [developer.withings.com/](https://developer.withings.com/) — Withings+ requirement from October 12, 2026, Public API scope, quickstart, EU and US clouds (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/developer-account/create-your-accesses-no-medical-cloud/](https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/developer-account/create-your-accesses-no-medical-cloud/) — free access with no prerequisites, application credentials, team roles (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/get-access/oauth-web-flow/](https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/get-access/oauth-web-flow/) — access to historical data, 30-second code exchange (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/get-access/oauth-authorization-url/](https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/get-access/oauth-authorization-url/) — authorization URL, state, scopes, demo user (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/get-access/sign-your-requests/](https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/get-access/sign-your-requests/) — HMAC SHA-256 request signing with a nonce (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/get-access/access-and-refresh-tokens-no-recover/](https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/get-access/access-and-refresh-tokens-no-recover/) — token lifetimes and the requesttoken call (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/data-api/notifications/notification-overview/](https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/data-api/notifications/notification-overview/) — 120 requests per minute, retries, escalation, delivery times, securing notifications (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/data-api/notifications/notification-subscribe/](https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/data-api/notifications/notification-subscribe/) — callback URL requirements and restricted mode (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/data-api/notifications/notification-content/](https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/data-api/notifications/notification-content/) — notification categories and payload fields (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/data-api/fetch-data-example/](https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/data-api/fetch-data-example/) — fetching after a notification, lastupdate (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/data-api/all-available-health-data/](https://developer.withings.com/developer-guide/v3/data-api/all-available-health-data/) — biomarker catalogue and the Advanced Biomarkers plan (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/maintain-your-integration/understand-our-timeline-for-notice/](https://developer.withings.com/developer-guide/v3/maintain-your-integration/understand-our-timeline-for-notice/) — notice periods for changes (checked 2026-10-17) - [developer.withings.com/developer-guide/v3/maintain-your-integration/track-changes-on-our-services/](https://developer.withings.com/developer-guide/v3/maintain-your-integration/track-changes-on-our-services/) — developer updates portal and mailing list (checked 2026-10-17) ## FAQ ### Is the Withings API free? Getting started is. Withings' setup page says there are no prerequisites and free access is provided on its EU Medical Cloud. Withings also announced that accounts created after October 12, 2026 need a Withings+ membership to share data with an app on the Start for Free plan, with Enterprise lifting that requirement for specific use cases; that notice was no longer on its developer home page on October 22, 2026, so confirm it with Withings. [Permalink](https://aifitnessapi.com/integrate/withings-api#faq-1) ### How does Withings OAuth work? Send the user to https://account.withings.com/oauth2_user/authorize2 with your client_id, scopes such as user.metrics and user.activity, a redirect_uri and a state value. The code that comes back is valid for only 30 seconds; exchange it with the requesttoken action, signed with HMAC SHA-256 and a fresh nonce from Withings' signature service. [Permalink](https://aifitnessapi.com/integrate/withings-api#faq-2) ### How long do Withings access tokens last? Withings documents 3 hours for an access token and 1 year for a refresh token. Every refresh issues a new refresh token, and the previous one expires 8 hours later or as soon as the new access token is used, so store the newest pair every time or you can lose access. [Permalink](https://aifitnessapi.com/integrate/withings-api#faq-3) ### Does the Withings API have webhooks? Yes, as data notifications. You subscribe an HTTPS callback URL per category, such as weight or sleep, and Withings POSTs the user ID, category and time window, typically within 2 minutes. It retries failed deliveries for about 5 hours, cancels a subscription after 20 days of failures, and never redelivers a missed notification. [Permalink](https://aifitnessapi.com/integrate/withings-api#faq-4) ### What is the Withings API rate limit? Withings says the standard API enforces 120 requests per minute across your application, which is why it recommends notifications over polling. The Enterprise plan unlocks higher limits and dedicated support; Withings' plans page did not render when we read the site, so we do not quote its prices. [Permalink](https://aifitnessapi.com/integrate/withings-api#faq-5)