Required Web Services

In order to embed Withings WebViews, the partner must be able to set up a server that will host at least the following web services used by your mobile application or Withings servers:

  • User Creation web service: called by your application on your server. This web services needs to call the Withings User Creation API (refer this section).
  • Token Management web service: called by your application on your server. This web services needs to fetch fresh tokens from Withings and render them to your application on-demand when the end user wants to manage his devices (refer this section).
setup_flow
Technical overview of the Initial Setup flow
usage_flow
Technical overview of the Device usage flow

User Creation API

In order to use the Withings devices, a Withings account is required. You will need to use the User Creation API to create a Withings account. This web service returns valid API tokens so your application is able to open the WebViews (installation and device settings WebViews)

Base URL

The base URL for the User Creation API is:

https://wbsapi.withings.net/v2/sdk

The base URL for the User Creation API on the HIPAA Cloud is:

https://wbsapi.us.withingsmed.net/v2/sdk

Query parameters

The following table specifies the POST parameters the partner must set to call the User Creation API.

NameTypeRequiredComments
actionstringyesService action name. Must take the string value createuser.
client_idstringyesClient id available here or here for HIPAA and HDS Cloud.
noncestringyesA random token used to prevent replay attacks (Cf. Signature v2 - Getnonce)
signaturestringyesHash of params (see Signature hash protocol).
mailingprefbooleanyesSpecifies if customer accepted Withings commercial contacts. Possible values are: 0 = REFUSED / 1 = ACCEPTED.
birthdateintegeryesUnix timestamp of user's birthdate
measuresjsonyesEnd user height and weight measures (refer to Measure model)
genderintegeryesEnd user gender. Possible values are: 0 = MAN / 1 = WOMAN.
preflanglocal_codeyesEnd user language preferences. Possible values are listed below
unit_prefjsonyesEnd user unit preferences (refer to Unit model)
timezonetimezoneyesEnd user timezone using the TZ database name (Ex: Europe/Paris, America/New_York)
emailemailyesEnd user email that will be used to create Withings partner account.
shortnamestringyesEnd user shortname (used on the scale device screen when a user is selected). Shortname must respect the following regex: /^[a-zA-Z0-9]{3}$/ (either letters or numbers, special characters and spaces are not allowed). For example: JDO for John Doe.
external_idstringyesPartner end-user unique identifier.
lastnamestringnoEnd-user lastname (if not set, will take the same value as shortname).
firstnamestringnoEnd user firstname (if not set, will take the same value as shortname).
phonenumberstringnoPhone number in E.164 format. End user will receive a verification code on this phone number for 2 factor authentication if they wish to securely access the data of their program in the Withings app in the future (recommended)
recovery_codestringnoRecovery code can be used by end user as a 2nd authentication factor in the Withings app if they wish to securely access the data of their program in the future. You will be responsible of securely providing this recovery code to your user if he asks for it.
goalsjsonnoEnd user goals for daily step or sleep (refer to Goals model)
important

A new nonce parameter has to be generated each the web service is called to prevent replay attacks. Get more information here

warning

The POST body should be encoded using x-www-form-urlencoded.

Query response

The reponse of the web services is the following one:

{
"status": <<integer>>,
"body": {
"user": {
"code": <<string>>,
"external_id": <<string>>
}
}

To generate the API tokens (access_token, refresh_token, csrf_token), the web service OAuth 2.0 - Get your access token needs to be used with the code that is rendered in the reponse of the User Creation call.

note

To get more information on possible status values, please refer her.

Signature hash protocol

In order to authenticate a partner, some Withings APIs use a hash value as a signature. The signature consists of the following parameters:

  • action
  • client_id
  • nonce

To generate a signature please follow these steps:

  • Generate a valid nonce using the service Signature v2 - Getnonce
  • Sort the values alphabetically by key name: action -> client_id -> nonce
  • Generate a string by concatenating values separated by a comma. The string should look this this: value1,value2,value3.
  • Apply an hmac hashing function on the string using the algorithm sha256 and your partner's client_secret (available in your Withings partner dashboard) as a secret key.
  • Add the hash string in the parameters under the signature key.
  • Refer to the following complete example to see how to generate a hash signature.

Example

Example of signature generation in PHP language:

<?php
$client_secret = 'My Partner Registration Client Secret';
$client_id = 'My Partner Registration Client Id';
$nonce = 'The nonce I retrieved using service: Signature v2 - Getnonce';
$signed_params = array(
'action' => 'createuser',
'client_id' => $client_id,
'nonce' => $nonce,
);
ksort($signed_params);
$data = implode(",", $signed_params);
$signature = hash_hmac('sha256', $data, $client_secret);
$call_post_params = array(
// Set the generated signature
'signature' => $signature,
// Set the signed parameters as clear text in the call post parameters
'action' => 'createuser',
'client_id' => $client_id,
'nonce' => $nonce,
// Set other parameters requested to call the service (here we are calling "SDK v2 - Createuser")
'birthdate' => 1563746400
// [...]
);
// Then call the service by using the $call_post_params array as post parameters
?>

Token Management API

Once you have generated the first API tokens after the end-user User Creation, you need to manage the API tokens and refresh them when required or when your mobile app is requesting fresh tokens using the web service OAuth 2.0 - Refresh your access token.

Available languages

CountryLanguageLocale Code
BelgiumDutch (BE)nl_BE
BelgiumFrench (BE)fr_BE
BulgariaBulgarianbg_BG
CanadaEnglish (CA)en_CA
CanadaFrench (CA)fr_CA
ChinaChinese (simplified)zh_CN
Czech RepublicCzechcs_CZ
DenmarkDanishda_DK
FranceFrench (FR)fr_FR
GermanyGermande_DE
HungaryHungarianhu_HU
ItalyItalianit_IT
JapanJapaneseja_JP
KoreaKoreanko_KO
LithuaniaLithuanianlt_LT
LithuaniaRussianru_LT
PolandPolishpl_PL
PortugalPortuguesept_PT
RussiaRussianru_RU
SlovakiaSlovaksk_SK
SpainSpanish (ES)es_ES
SwedenSwedishsv_SE
TaiwanChinese (simplified)zh_TW
ThailandThaith_TH
U.S.English (US)en_US
U.S.Spanish (US)es_US
UKEnglish (UK)en_EN
UkraineRussianru_UA
UkraineUkrainianuk_UA