Activate API

Now that we know how to sign requests, we can proceed with the activation of the device. We're going to use the Activate API for this, it serves the following purposes:

Create a Withings user account
Link devices specified by their MAC addresses in the request to the created user
Activate the cellular device service and enable invoicing

Notes

To activate the Withings HUB cellular service, the MAC address of the Withings HUB must be included in the list of mac_addresses along with other Withings devices.
Trying to activate a device that isn't authorized will result in an error.
The authorization code returned in this API is valid for 10min.

Once you've activated your device, you can go to the next step to learn how to exchange the code for an access and refresh token.

Parameters

Refer to the API reference or

Toggle me!

Parameter	Required	Type	Description
action	Yes	string	The service action name. Must be set to `activate`.
client_id	Yes	string	The ID of your client.
nonce	Yes	string	A random token used to prevent replay attacks. Refer to the Signature v2 - Getnonce.
signature	Yes	string	A hash of the parameters. See Signature hash protocol for details.
mailingpref	Yes	boolean	Indicates whether the customer has accepted Withings commercial contacts.
birthdate	Yes	integer	The Unix timestamp of the user's birthdate.
measures	Yes	json_string	User measures (refer to Measures model).
gender	Yes	integer	Gender of the user: `0` for male, `1` for female.
preflang	Yes	string	User's language preference (e.g., `en_EN`, `fr_FR`).
unit_pref	Yes	json	User's unit preferences (refer to Unit preferences model).
email	Yes	email	The user's email address.
timezone	Yes	timezone	User's timezone (e.g., `Europe/Paris`, `America/New_York`). A complete list can be found here.
shortname	Yes	string	A three-character representation of the end user (e.g., `ROB` for Robert). Must match regex: `/^[a-zA-Z0-9]{3}$/`.
external_id	Yes	string	A unique identifier used by the partner to identify the end user.
mac_addresses	Yes	macaddress	List of Withings device MAC addresses to be linked to the created user (e.g., `["00:24:e4:xx:xx:xx","00:24:e4:xx:xx:xx"]`). See Find a device serial number.
redirect_uri	Yes	partner_redirect_uri	The URI to redirect the user after authorization. This must be set as the Callback URL in your partner application. You can specify multiple URLs separated by commas.
firstname	No	string	The user's first name. Defaults to the value of `shortname` if not set.
lastname	No	string	The user's last name. Defaults to the value of `shortname` if not set.
phonenumber	No	string	Phone number in E.164 format. Used for two-factor authentication verification (recommended).
recovery_code	No	string	A recovery code that can be used as a second authentication factor in the Withings app.
goals	No	json	User goals (refer to Goals model).

Snippet

const axios = require('axios');
const { sign, getNonce } = require('../signature');

// Constants
const API_ENDPOINT = 'https://wbsapi.withings.net';
const OAUTH2_GRANT_TYPE_AUTHORIZATION_CODE = 'authorization_code';
const REDIRECT_URI = 'YOUR_REDIRECT_URI';
const CLIENT_ID = 'YOURCLIENTID';
const CLIENT_SECRET = 'YOURCLIENTSECRET';

const MEASURE_TYPE_HEIGHT = 4;
const MEASURE_TYPE_WEIGHT = 1;
const UNIT_HEIGHT_M  = 6;
const UNIT_HEIGHT_IN = 7;
const UNIT_WEIGHT_KG = 1;
const UNIT_WEIGHT_LB = 2;
const UNIT_WEIGHT_STLB = 14;
const UNIT_DISTANCE_KM = 6;
const UNIT_DISTANCE_YD = 8;
const UNIT_TEMPERATURE_C = 11;
const UNIT_TEMPERATURE_F = 13;


async function activate(nonce, mac_addresses, user) {
  const params = {
    action: 'activate',
    client_id: CLIENT_ID,
    nonce,
    mac_addresses: JSON.stringify(mac_addresses),
    email: user.email,
    shortname: user.shortname,
    gender: user.gender,
    birthdate: user.birthdate,
    measures: JSON.stringify(user.measures),
    external_id: user.external_id,
    mailingpref: user.mailingpref,
    unit_pref: JSON.stringify(user.unit_pref),
    preflang: user.preflang,
    timezone: user.timezone,
  };
  if (user.firstname) {
    params.firstname = user.firstname;
  }
  if (user.lastname) {
    params.lastname = user.lastname;
  }
  if (user.phonenumber) {
    params.phonenumber = user.phonenumber
  }
  if (user.goals) {
    params.goals = user.goals;
  }
  if (user.recovery_code) {
    params.recovery_code = user.recovery_code;
  }
  params.signature = sign(params, CLIENT_SECRET);
  const { data } = await axios.post(API_ENDPOINT + '/v2/user', params);
  return data;
}

async function main() {
  const mac_addresses = ['00:24:e4:78:5c:3e', '00:24:e4:61:5a:3d'];
  const measures  = [
    { value: 190, unit: -2, type: MEASURE_TYPE_HEIGHT }, //1m90
    { value: 90, unit: 0, type:  MEASURE_TYPE_WEIGHT} //90kg
  ];
  const unit_pref = {
    weight: UNIT_WEIGHT_KG,
    height: UNIT_HEIGHT_M,
    distance: UNIT_DISTANCE_KM,
    temperature: UNIT_TEMPERATURE_C
  };
  const mandatory_params_user = {
    mailingpref: 0,
    birthdate: 848166152,
    measures, // measurements should always be passed in kg/m
    gender: 0,
    preflang: 'en_US',
    unit_pref,
    email: 'john.doe@example.com',
    timezone: 'America/New_York',
    shortname: 'HNI',
    external_id: 'my-external-id' //id of this user on your side
  }
  const optional_params_user  = {
    firstname: 'John', //if not set, will take the same value as shortname
    lastname: 'Doe', //if not set, will take the same value as shortname
    phonenumber: '+551155256325', //Phone number in E.164 format.
    recovery_code: 'abcde12345',
    goals: null
  }
  const user = {...mandatory_params_user, ...optional_params_user};
  const now = Math.round((Date.now() / 1000));
  const response = await activate(await getNonce(now, CLIENT_ID), mac_addresses, user);
  console.log(JSON.stringify(response));
}

main();

Response

{
    "status": 0,
    "body": {
        "user": {
            "code": "4ab52f3da1e1c8da346ec68ff26a45104c4859f6",
            "external_id": "my-external-id"
        },
        "devices": [
            {
                "deviceid": "1f5cd788497dc62392793c3e87791f6183ae244a",
                "mac_address": "00:24:e4:72:9a:68",
                "type": "Activity Tracker",
                "battery": "low",
                "model": "Activite Steel HR",
                "model_id": 55,
                "timezone": "Europe/Paris",
                "last_session_date": 1569996478
            }
        ]
    }
}

Possible Errors

Invalid Signature

{
    "status": 503,
    "body": {},
    "error": "Invalid Params: Invalid HMAC signature"
}

Unauthorized device

{
    "status": 277,
    "body": {},
    "error": "Unauthorized - Mac addresses [00:24:e4:72:9a:68] not allowed for this partner (wrong consumer)"
}

Invalid Parameter

{
    "status": 503,
    "body": {},
    "error": "Invalid Params wrong HEIGHT value : out of range"
}

Solutions

Integration Guides

Tutorials

API Upgrades