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.
The Validic Inform integration to Withings Pro uses the Withings US Medical (HIPAA compliant) cloud. The Withings Enterprise Plan is strongly encouraged for scaling programs with Withings cellular devices.
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. The required steps are:
Provision a user in Validic Inform
Dropship and activate the cellular device using Withings Pro APIs
Establish the user device connection between Withings Pro and Validic Inform
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.
1. 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"
}
2. 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:
Note:
Withings base url:
https://wbsapi.us.withingsmed.netThe 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.
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.
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
3. 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:
All values are strings
scopes is an array of strings
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.
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 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:
The Withings Pro Inform integration has the source ‘type’: withings_pro
The Withings Pro Inform integration supports the following data metrics:
Metric Type | Resource | Definition | Data Type | Unit |
| measurements | Body weight measurement of the individual. | float | kg |
| measurements | The diastolic blood pressure measurement of the individual. | float | mmHg |
| measurements | The systolic blood pressure measurement of the individual. | float | mmHg |
| measurements | The heart rate reading of the individual. | integer | bpm |
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.
{
"data": [
{
"checksum": "d65....",
"created_at": "2023-07-10T19:07:37.132Z",
"deleted_at": null,
"end_time": "2023-07-05T12:41:17Z",
"id": "b6.....",
"log_id": "4653611801",
"metrics": [
{
"type": "body_weight",
"origin": "device",
"unit": "kg",
"value": 53.950
}
],
"offset_origin": "source",
"source": {
"type": "withings_pro",
"device": "body pro"
},
"start_time": "2023-07-05T12:41:17Z",
"tags": [],
"type": "measurement",
"user": {
"organization_id": "649d831SAMPLE0e040cf5",
"user_id": "649d83SAMPLEd60352",
"uid": "cellular-test"
},
"user_notes": [],
"utc_offset": -18000,
"version": "1.0"
},
{
"checksum": "4b5d8b....",
"created_at": "2023-07-30T12:35:56.332Z",
"deleted_at": null,
"end_time": "2023-07-05T12:41:17Z",
"id": "be27c58b....",
"log_id": "4640769875",
"metrics": [
{
"type": "diastolic",
"origin": "device",
"unit": "mmHg",
"value": 83
},
{
"type": "systolic",
"origin": "device",
"unit": "mmHg",
"value": 139
},
{
"type": "pulse",
"origin": "device",
"unit": "bpm",
"value": 98
}
],
"offset_origin": "source",
"source": {
"type": "withings_pro",
"device": "bpm connect pro"
},
"start_time": "2023-07-05T12:41:17Z",
"tags": [],
"type": "measurement",
"user": {
"organization_id": "649d831SAMPLE0e040cf5",
"user_id": "649d83SAMPLEd60352",
"uid": "cellular-test"
},
"user_notes": [],
"utc_offset": -18000,
"version": "1.0"
}
]
}
Details on using the Inform Streaming API and REST APIs can be found in our online technical documentation.