Connect Withings
Link your Withings account to pull body composition, vitals, and Sleep Analyzer summaries 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 and sleep summaries.
A background job imports up to 12 months of Withings measurement and sleep history. The dashboard will populate once the sync completes.
How data stays fresh
Webhooks (real-time)
Withings sends push notifications when new data is available. VitalTrends processes body composition, vitals, and sleep notifications after Withings uploads the source reading.
Catch-up sync (background)
An hourly job checks whether your Withings data is stale. Stale accounts trigger a catch-up sync to fetch any missed measurements or sleep summaries.
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.
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.