How to Integrate the Withings API (2026)

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.

Access and approval#

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:

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:

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:

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:

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#

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. The rest of the cluster is at how to integrate a fitness or health API.