Connect Withings
Link your Withings account to pull body composition, vitals, sleep, and workouts directly into VitalTrends. New readings sync automatically.
Steps
An active subscription is required to connect integrations. Go to Pricing to get started.
Go to Settings → Connections. You will see a Withings card showing "Not connected".
You will be redirected to Withings's OAuth authorization page. Log in with your Withings account credentials if prompted.
Review the permissions and click Allow this app. VitalTrends requests read-only access to your measurements, sleep, and activity data.
Background jobs import Withings measurement, sleep, and available workout history. The dashboards populate as each sync completes.
How data stays fresh
Webhooks (real-time)
Withings sends push notifications when new data is available. VitalTrends processes body composition, vitals, activity and workout, and sleep-summary notifications after Withings uploads the source data.
Re-syncing workouts
The hourly catch-up also rechecks the last 30 days of workouts, including workouts removed in Withings. On the Withings dashboard, Force sync rechecks that same period. Use Re-sync a workout date range for older changes, up to one year per request. VitalTrends removes missing Withings workouts only after a complete, valid response for the requested period. Records supplied by other sources remain, so a shared workout may still appear. Recent measurements and sleep are refreshed alongside manual workout syncs.
Catch-up sync (background)
An hourly job checks whether your Withings data is stale. Stale accounts trigger a catch-up sync to fetch missed measurements, sleep summaries, or workouts.
Workout matching
Native Withings workouts appear in the main Workouts timeline and the unified workouts API. When the same physical session also exists in Apple Health, WHOOP, Oura, Hevy, Strava, or a VitalTrends training log, the normal matching policy combines it into one session while preserving every source. Intraday heart rate and automatic SpO2 samples are included when Withings makes them available.
Reading the dashboard
The Latest snapshot cards always show your most recent Withings readings, even when those readings fall outside the selected chart period. The Trends range control updates the charts and record tables below it.
The fat and lean mass chart uses two color-matched vertical scales so smaller changes remain readable: muscle mass uses the purple scale on the left, and fat mass uses the amber scale on the right. Hover values follow the scale assigned to each line.
Understanding Withings measurements
Withings sends measurements as a group from a single weigh-in or vitals reading. VitalTrends stores that group as one row and keeps the original measurement time from Withings.
| Field | Meaning |
|---|---|
measured_at | The time Withings recorded the measurement. |
weight_kg | Body weight in kilograms. The dashboard converts it to your profile unit preference when needed. |
fat_ratio_pct | Body fat percentage from the Withings measurement. |
fat_mass_kg | Estimated fat mass in kilograms. |
fat_free_mass_kg | Estimated non-fat mass in kilograms. |
muscle_mass_kg | Estimated muscle mass in kilograms, when your device provides it. |
bone_mass_kg | Estimated bone mass in kilograms, when your device provides it. |
hydration_kg | Estimated body water mass in kilograms, when your device provides it. |
heart_pulse | Pulse from the Withings reading, when available. |
systolic_bp / diastolic_bp | Blood pressure values from Withings devices that support blood pressure. |
Some fields may be empty because not every Withings device measures every body-composition or vitals metric. Empty fields mean Withings did not provide that value for that measurement; they do not mean VitalTrends rejected it.
Understanding Sleep Analyzer summaries
Withings Sleep Analyzer data is stored separately from scale and vitals measurements because it describes a sleep period instead of a point-in-time reading.
| Field | Meaning |
|---|---|
start_at / end_at | The sleep period reported by Withings. |
sleep_score | Withings sleep quality score. |
light_sleep_duration_seconds, deep_sleep_duration_seconds, rem_sleep_duration_seconds | Sleep stage durations in seconds. |
wakeup_duration_seconds / wakeup_count | Awake time and number of wakeups during the sleep period. |
hr_average, hr_min, hr_max | Sleeping heart rate values when available. |
rr_average, rr_min, rr_max | Sleeping respiratory rate values when available. |
snoring_seconds / snoring_episode_count | Snoring duration and episode count. |
breathing_disturbances_intensity | Withings breathing disturbances intensity value. |
apnea_hypopnea_index | Apnea-hypopnea index from compatible Withings devices. |
Sleep Analyzer fields may be empty when the user does not own a compatible device, the device has not produced that metric, or Withings did not include the value in the source summary.
Disconnecting Withings
Go to Settings → Connections and click Disconnect next to Withings. This stops all future syncs. Your historical Withings data stays in VitalTrends.
Troubleshooting
No data after connecting
The initial import is still running. Wait a minute and refresh. If Withings data still does not appear, try disconnecting and reconnecting.
Connection shows "Reconnection needed"
Withings OAuth tokens expire or can be revoked. Click Reconnect on the Connections page to re-authorize. This happens automatically if you revoke access in the Withings app.
Connection shows "Enable workouts"
Your connection is healthy but was authorized before native workout support. Click Enable workouts and approve the added read-only activity permission. Existing measurements and sleep data remain available during the upgrade.
Weight appears in wrong unit
VitalTrends stores weight in kilograms (as provided by the Withings API) and converts to your preferred unit based on your profile settings. Check Settings → Profile to update your unit preference.
Some body composition fields are blank
Withings only sends fields your device measured for that weigh-in. For example, a basic scale may send weight_kg without muscle_mass_kg, bone_mass_kg, or hydration_kg.
No Sleep Analyzer data appears
Sleep Analyzer charts require a compatible Withings sleep device and at least one synced sleep summary. Users with only a scale or blood pressure monitor will still see their body and vitals data without sleep-specific fields.