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 to this section for more information).
• 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 to this section for more information).

Technical overview of the Initial Setup 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.

Name	Type	Required	Comments
action	string	yes	Service action name. Must take the string value createuser.
client_id	string	yes	Client id available here.
nonce	string	yes	A random token used to prevent replay attacks (Cf. Signature v2 - Getnonce)
signature	string	yes	Hash of params (see Signature hash protocol).
mailingpref	boolean	yes	Specifies if customer accepted Withings commercial contacts. Possible values are: 0 = REFUSED / 1 = ACCEPTED.
birthdate	integer	yes	Unix timestamp of user's birthdate
measures	json	yes	End user height and weight measures (refer to Measure model)
gender	integer	yes	End user gender. Possible values are: 0 = MAN / 1 = WOMAN.
preflang	local_code	yes	End user language preferences. Possible values are listed below
unit_pref	json	yes	End user unit preferences (refer to Unit model)
timezone	timezone	yes	End user timezone using the TZ database name (Ex: Europe/Paris, America/New_York)
email	email	yes	End user email that will be used to create Withings partner account.
shortname	string	yes	End 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_id	string	yes	Partner end-user unique identifier.
lastname	string	no	End-user lastname (if not set, will take the same value as shortname).
firstname	string	no	End user firstname (if not set, will take the same value as shortname).
phonenumber	string	no	Phone 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_code	string	no	Recovery 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.
goals	json	no	End user goals for daily step or sleep (refer to Goals model)

info

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

danger

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 here.

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

Country	Language	Locale Code
Belgium	Dutch (BE)	nl_BE
Belgium	French (BE)	fr_BE
Bulgaria	Bulgarian	bg_BG
Canada	English (CA)	en_CA
Canada	French (CA)	fr_CA
China	Chinese (simplified)	zh_CN
Czech Republic	Czech	cs_CZ
Denmark	Danish	da_DK
France	French (FR)	fr_FR
Germany	German	de_DE
Hungary	Hungarian	hu_HU
Italy	Italian	it_IT
Japan	Japanese	ja_JP
Korea	Korean	ko_KO
Lithuania	Lithuanian	lt_LT
Lithuania	Russian	ru_LT
Poland	Polish	pl_PL
Portugal	Portuguese	pt_PT
Russia	Russian	ru_RU
Slovakia	Slovak	sk_SK
Spain	Spanish (ES)	es_ES
Sweden	Swedish	sv_SE
Taiwan	Chinese (simplified)	zh_TW
Thailand	Thai	th_TH
U.S.	English (US)	en_US
U.S.	Spanish (US)	es_US
UK	English (UK)	en_EN
Ukraine	Russian	ru_UA
Ukraine	Ukrainian	uk_UA