This article pertains to: ​INFORM (V2)

How are Withings Pro cellular devices connected to Validic Inform? How is device activation handled when devices have been dropshipped directly patients by Withings?

Validic clients will use a series of API endpoints to connect a Withings Pro cellular device to Validic Inform on behalf of their end users. End users will simply receive the activated, connected cellular device and start using it.

There is no need for the end user to perform any connection or authorization process within Validic Inform. However, consent can optionally be captured directly by the Validic client if desired to comply with program terms.

This page details the process for completing device activation, user authorization, and connection to Validic Inform for Validic clients who want to have Withings dropship cellular devices directly to the patient or end user. There is a similar guide detailing the same workflow for Validic clients who want to activate and use cellular devices that have been bulk shipped to them by Withings.

User Authorization & Data Processing for Dropshipped Cellular Devices

Overview

Withings cellular devices are offered with two procurement workflows:

• Withings can dropship the device to the end user on behalf of the client

• Withings can bulk ship devices to the client, then the client will distribute the devices to end users

End users cannot purchase Withings Pro cellular devices directly from Withings. These devices must be acquired through a client who has signed a contract with Withings for Withings Cellular Solution.

Validic Inform does not have access to the PHI necessary to dropship or bulk ship devices, therefore Inform clients using Withings cellular devices are responsible for acquiring the devices and implementing the Withings API calls necessary for the procurement model that works best for their use case.  The Validic Inform integration to Withings Pro can support either workflow (basically, Validic Inform is agnostic to the method used to acquire and activate the cellular device). 

Per Withings' documentation, regardless of whether the client wants to use dropshipping or bulk shipping, a token exchange will need to be completed using the Withings OAuth2-v2 Requesttoken endpoint so that the user’s readings can be retrieved from the Withings API. The response from this endpoint includes the information that Validic Inform needs to manage tokens, subscribe to notifications, and retrieve and process data. Therefore, an onboarding endpoint is established in the Validic Inform platform to receive the needed information. 

This guide details the Withings Pro and Inform APIs that clients will need to implement in order to create and manage the data connection between Withings Pro and Validic Inform on behalf of the end user.

Open

The required steps are:

1. Provision a user in Validic Inform

2. Dropship and activate the cellular device using Withings Pro APIs

3. Establish the user device connection between Withings Pro and Validic Inform

4. Receive Withings Pro data in Validic Inform

We also cover disconnecting the user device connection, in case the user leaves your program.

At the end of this guide there is a sample of what Withings Pro cellular data will look like in the Inform APIs.

Let’s get into the individual steps.

Provision User in Validic Inform

Sample Request

Content-Type: application/x-www-form-urlencoded

POST https://api.v2.validic.com/organizations/:orgid/users?token=:token

{  

   "uid":"277040620sol3"

}

Where:

:orgid is the Validic Organization ID to associate the user with

:token is the Organization access token

uid is the client’s user identifier

Sample Response

{

    "id": "59b0664cf758800001e13ea9",

    "uid": "277040620sol3",

    "marketplace": {

        "token": "ee889ef9d7fb7a9644c97ef9d69ZSAMPLEa0be23352bdee46a775c066ef0f890",

        "url": "https://syncmydevice.com?token=ee889ef9d7fb7a9644c97ef9d69ZSAMPLEa0be23352bdee46a775c066ef0f890"

    },

    "mobile": {

        "token": "7c001f84255SAMPLE8c168ba563035"

    },

    "sources": [],

    "created_at": "2023-07-06T21:19:08Z",

    "updated_at": "2023-07-06T21:19:08Z"

}

Dropship and Activate Device with Withings Pro APIs

Withings documentation: https://developer.withings.com/developer-guide/v3/integration-guide/dropship-cellular/logistics-api/create-user-order  

These are the APIs that the client must implement into their own workflow:

• Signature-v2 Getnonce

• Dropshipment-v2 Createuserorder

• OAuth2-v2 Requesttoken

Note: 

1. Withings base url: https://wbsapi.us.withingsmed.net

2. The information included in the response received from the Withings OAuth2-v2 Requesttoken endpoint will be used in the next step to establish the user device connection in Inform. 

3. The client will not use the “Notify Subscribe” endpoint in the Withings API. The Validic Inform integration will subscribe for data updates automatically once the user connection is established.

4. If the client prefers to have Withings devices bulk shipped, that is also possible using the instructions here: Withings Pro Inform Integration Bulk Shipping Process

Establish User Device Connection

Sample Request

Content-Type: application/json

POST https://api.v2.validic.com/organizations/:orgid/users/:uid/credentials?token=:token 

{

    "source": "withings_pro",

    "source_uid": :withingsuserid,

    "access_token": :withingsaccesstoken,

    "refresh_token": :withingsrefreshtoken,

    "expires_at": :withingstokenexpiration,

    "scopes": [ :withingsscopes

    ]

}

Where:

:orgid is the Validic Organization ID to connect the user to

:uid is the client’s user identifier

:token is the Organization access token

And the following information is passed from the OAuth2-v2 Requesttoken response:

:withingsuserid is the Withings user identifier (userid)

:withingsaccesstoken is the Withings user access token (access_token)

:withingsrefreshtoken is the Withings user refresh token (refresh_token)

:withingstokenexpiration is the UTC expiry of the user access token - see notes 3 and 4 below.

:withingsscopes is the granted Withings scopes (scopes)

Note: 

1. Once this endpoint is used to submit the user’s Withings tokens to Validic Inform, Inform will be the source of truth for the tokens. Inform will update and manage the tokens to ensure data access is maintained, therefore, no other processes should make calls to Withings to adjust the tokens.

   1. If the tokens must be re-generated for any reason then the user must be disconnected from Withings Pro in Inform first. And then new tokens must be submitted to Inform using the “Establish User Device Connection“ endpoint.

2. All values are strings

3. scopes is an array of strings

4. Clients will calculate the expires_at date/time based on the time the Withings’ OAuth2-v2 Requesttoken response is received by adding Withings' expires_in to the response date/time.

5. expires_at format must match the following: YYYY-MM-DDTHH:MM:SSZ (e.g., 2023-07-12T23:00:00Z)

Example Request Body

{

   "source": "withings_pro",

   "source_uid": "12470593",

   "access_token": "6dbc418e4e8bc3fSAMPLEace34dda9e63e67f",

   "refresh_token": "22893c4b7ddf4SAMPLE70f4852e72038d936fc7",

   "expires_at": "2023-07-31T11:31:01Z",

   "scopes": [

      "user.getinfo", 

      "user.info", 

      "user.metrics", 

      "user.activity", 

      "device.info", 

      "device.environment", 

      "sdk.accountowner", 

      "user.sleepevents"

   ]

}

Sample Response

202 Accepted

Disconnect User

The Validic standard or custom marketplace is used to determine the user’s current connection status to Withings Pro. The Withings Pro source can be disconnected using the disconnect_url returned by the Validic marketplace, such as the following:

GET https://syncmydevice.com/?token=:token&format=json

Where:

:token is the user’s Validic Inform marketplace token

Sample Response

[

   {

      "type": "withings_pro",

      "connected": true,

      "logo_url": "//assets.prod.validic.com/cmapi/images/sources/withings_pro.png",

      "display_name": "Withings Pro",

      "tagline": "",

      "disconnect_url": "https://syncmydevice.com/auth/withings_pro/disconnect?token=2f4e54SAMPLEae7b311743cf04df78"

   }

]

In this example, accessing the url ‘https://syncmydevice.com/auth/withings_pro/disconnect?token=2f4e54SAMPLEae7b311743cf04df78’ will disconnect the user from the Withings Pro source in the Inform marketplace.

Withings Pro Data

The Withings Pro Inform integration supports the following devices:

• Body Pro

• BPM Connect Pro

The Withings Pro Inform integration has the source ‘type’: withings_pro

The Withings Pro Inform integration supports the data metrics defined on the Standard Metrics Used Per App page (see “Withings Pro” app).

Sample Data

The below example illustrates a single weight measurement using the Body Pro scale and a single blood pressure measurement using the BPM Connect Pro blood pressure monitor. 

This sample shows how these readings appear in the Validic Inform Streaming API and REST API.

Details on using the Inform Streaming API and REST APIs can be found in our online technical documentation.