Skip to main content


Access Token

This token is unique to each user. It gives access to the API and is linked to your app. It expires after three hours. It can be refreshed using a refresh_token.

Authentication code

Once the user allows your app to access their data, this code is generated and set in the redirect URL. It can be used once and is valid for 30 seconds.

Breathing Disturbance

Recommended ranges for the breathing disturbance intensity:

  • From 0 included to 30 excluded: Low breathing disturbances
  • From 30 included to 60 excluded: Medium breathing disturbances
  • Higher or equal to 60: High breathing disturbances
  • The user has to enter valid settings in his profile (age, height, weight, gender) to get a correct breathing disturbance intensity value.
  • Breathing disturbance intensity is only calculated for nights longer than five hours

Callback URL

The partner URL is called by our system to send notifications through HTTP POST requests. Make sure that your server can handle a HTTP HEAD request called to verify the validity of your URL.


Your URL must:

  • start with https
  • be a valid URL, provided as a URL-encoded string. Please see w3schools URL encoding reference to learn more about URL encoding.
  • not be greater than 255 characters.
  • not contain an IP or 'localhost'. Only ports 80 and 443 are permitted.

Client ID and Client Secret

Required parameters used to authenticate your request during the OAuth 2.0 process. You can get them from your Developer application Dashboard.

Heart Rate Zones

Heart rate zones are calculated based on user age and maximum heart rate (hr_max). Knowing their heart rate zones can help users improve their health and fitness and stay in an appropriate heart rate range for their body.

  • Light: From 0% included to 50% excluded of maximal heart rate (hr_max) User heart rate will be in the light zone at rest and during daily activities such as brushing teeth, preparing food, or light walking. A heart rate in this zone does not indicate exercise, and will not promote cardiovascular conditioning.

  • Moderate: From 50% included to 70% excluded of maximal heart rate (hr_max) The user's heart rate will hit this zone during most moderate-intensity exercise. At this heart rate, the user's respiration will deepen, as more oxygen is inhaled with each breath, but the intensity should be sustainable. Exercising in this zone is best for improving overall health, basic endurance, and fat burning.

  • Intense: From 70% included to 90% excluded of maximal heart rate (hr_max) The user's heart rate will hit this zone during most high-intensity exercise. Once the user's heart rate enters this zone, their respiration rate will increase, and it will be difficult to speak more than a few words at a time. Exercising in this zone is best for improving aerobic fitness, performance and speed.

  • Maximum: From 90% included to 100% included of maximal heart rate (hr_max) This heart rate range can only be sustained for a few minutes at most. Completing short intervals of exercise in this zone can help athletes improve their speed and aerobic performance. There is no need to hit a heart rate in this zone for general health and fitness, and Withings recommends not exercising in this zone without consulting a doctor.

Refresh Token

This token is unique. It is linked to the user and your app. It is valid for one year. It is used to refresh the access_token. When you do this, a new refresh_token is sent back to you.

Restricted mode

In case you want to use a callback URL that does not respect imposed rules, you can enable the restricted mode. However, your partner application will be restricted: only ten users will be able to link to your application. To link an eleventh user, you will have to unlink one user or disable the restricted mode. The disabling requires your callback URLs to respect the rules specified here.


A scope is a permission that allows your app to access associated services. You have to specify the list of permissions during the OAuth 2.0 - Get your authentication step. The customer must give your app access to associated data. Refer to Withings API list to discover which scope we need to use.

Sleep events

Sleep events are triggered when users get in or out of bed. This feature is only available for Withings Sleep. For more information, see the notifications section.


Login required

Please log in to your Developer Dashboard in order to file a request.