The Tenovi HWI API allows third-party Clients to:

1) Receive measurement data from Tenovi Devices at a specified Webhook, or fetch measurement data directly from a specified Endpoint

2) Receive status updates (e.g. related to fulfillment) for Tenovi Devices at a specified Webhook.

3) Activate/Deactivate Tenovi Devices (Note: only activated devices will send measurement & status data; charges may apply when activating new devices)

4) Optionally include shipping information when activating a device, so that Tenovi (or the client, via our frontend dashboard) can provide fulfillment services (note, additional charges may apply)

Each of these features is executed/implemented using HTTPS requests.

For Features 1 & 2, the Client must register a callback Webhook using the Tenovi dashboard or API. The Tenovi API will then send a POST request with measurement data or status updates to these endpoints. All data sent via the API is in JSON format. Header-based authentication methods (e.g. Basic Auth) can be optionally included in the POST request, if required by the Client.

For Features 3 & 4, you need a valid API Key included in the request header. You can generate your API key using the Tenovi dashboard or API. Each API Key has a rate limit of 1 request per second. All requests to the API must be performed over HTTPS.

To authenticate an API request, the API key must be included in an HTTP Authorization header. The key should be prefixed by the string literal “Api-Key” with whitespace separating the two strings. For example:

                `Authorization: Api-Key TENOVI_API_KEY`

Specific documentation for each of the above features is included below.

Base URL

All API calls will use the following root URL:

https://api2.tenovi.com/clients/CLIENT_DOMAIN

Note, the Tenovi backend separates all client data in our database to ensure security & HIPAA compliance. For each client, a client-specific URL must be used when communicating with our API. Simply replace the CLIENT_DOMAIN field in the URL above with your custom domain (provided by your Tenovi representative) when making calls to our API.

The Tenovi Logistics API allows third-party Clients to receive measurement data from Tenovi Devices at a specified endpoint. The Client must provide Tenovi with a callback endpoint that the Tenovi API will POST to whenever a measurement is received from a Tenovi Device. All data sent via the API is in JSON format. Header-based authentication methods (e.g. Basic Auth) can be optionally included in the POST request, if required by the Client.

Multiple Webhooks can be added at the same time. The default behavior is for measurements to be sent to all Webhooks. However, users can configure devices to only POST to a single, user-selected Webhook using the “measurement_webhook_id” Device Property. See “Setting Device Properties” below for more information.

For devices that measure multiple metrics simultaneously (e.g. BPMs measure both blood_pressure and pulse metrics), webhooks can be configured to either send two separate POST requests for each measurement, or a single POST request with all simultaneous measurements included in a JSON array.

For either option, the “timestamp” field will be identical for coincident measurements. If multiple measurements of the same type are reported with the same timestamp, clients can use the “measurement_index” value included in the “filter_params” field to identify coincident measurements. Note, the measurement_index value is not guaranteed to be unique over time, so the timestamp field should always be referenced first. See below for more information.

The following data is included in each POST request:

An example JSON package is included below.

{

    “metric”: “blood_pressure”,

    “device_name”: “Tenovi BPM – L”,

    “hwi_device_id”: “12345678-abcd-1234-abcd-1234567890ab”,

    “patient_id”: “12345678-1234-12345678”,

    “hardware_uuid”: “fed091a643ff”,

    “sensor_code”: “10”,

    “value_1”: 120.00,

    “value_2”: 80.00,

    “created”: “2021-01-15T12:15:20.123597Z”,

    “timestamp”: “2021-01-15T12:14:49.000000Z”,

    “timezone_offset”: -7,

    “estimated_timestamp”: false,

    “filter_params”: {

       “measurement_index”: 15

    }

Fulfillment Webhooks

If Tenovi will be providing fulfillment services, after a Device has been requested, Tenovi will send a callback HTTPS POST request to a provided endpoint to indicate the device status (e.g. “Shipped” or “Connected”), tracking link, and the unique hardware_uuid for the physical device that was shipped to the patient.

The following data is included in each POST request:

An example JSON package is included below.

{

    “hwi_device_id”: “12345678-abcd-1234-abcd-1234567890ab”,

    “patient_id”: “12345678-1234-12345678”,

    “hardware_uuid”: “fed091a643ff”,

    “sensor_code”: “10”

    “device_name”: “Tenovi BPM”,

    “status “: “Shipped”,

    “tracking_link”: “ups.com/tracking-number”

}

Activating/Requesting Devices

Devices are activated/requested, as well as listed, read, and deactivated, through HTTP requests to the following endpoint:

/hwi/hwi-devices/

To Activate a new HWI Device, you must make a POST request to this endpoint using the appropriate JSON data in the payload (see our Redoc Documentation for specific details). Note, only one device with a given Sensor Code can be associated with a Tenovi Gateway at one time (see Sensor Codes below).

If successful, the HWI Device Activation Request will return a HWI Device object with an “id” parameter in the root object. This id must be saved and used as a unique identifier for this specific device. This id is included in the “hwi_device_id” field in the Webhook callbacks to allow data from a specific HWI Device to be associated with a particular patient in the Client’s software (see above). This id is also required to delete this specific HWI Device to remove it from your account, or Unlink the associated Gateway if the HWI Device cannot be deleted (HWI Devices cannot be deleted if they are attached to a Fulfillment Request that has been fulfilled). Charges may occur for devices that are not deleted/unlinked from a Gateway when no longer in use. If you forget to save the HWI Device id, you can retrieve it using the GET method on the hwi-devices endpoint.

HWI Device Activation Requests must reflect one of three possible real-world Use Cases: 1) devices are given to patients on-site (so the Gateway ID is known), 2) devices need to be shipped to the patient by a client’s internal staff, or 3) devices need to be shipped to the patient from Tenovi (NOTE: additional charges may apply for this service).

For Use Case #1: The nested Device object in the Activation Request must include the Gateway ID (for devices with a Sensor Code) or the IMEI (for cellular devices) in the “hardware_uuid” field. In this case, the “status” field of the returned HWI Device object will either be set to “Delivered” or “Unknown Gateway ID” if an invalid Gateway ID is used.

For Use Cases #2 and #3: The “hardware_uuid” field must be set to null, and the shipping information must be included in the nested “fulfillment_request” object. The “notify_emails” field of the “fulfillment_request” object is optional, but it can be used to pass in a list of comma-separated email addresses, which will be sent shipping update emails as updates occur for the newly requested Device. The “require_signature” field of the “fulfillment_request” object can be used to request signature confirmation of delivery; additional charges may apply.

For Use Case #2: The “client_will_fulfill” field of the “fulfillment_request” object must be set to true. In this case, the “status” field will be set to “Pending Shipment”.

For Use Case #3: The “client_will_fulfill” field should be set to false. In this case, the “status” field will be set to “Dropship Requested”. If only the Tenovi Gateway needs to be shipped to the patient (for example, because they already have a Gateway-compatible device on hand), the “ship_gateway_only” flag of the “fulfillment_request” object should be set to true.

Special Case for Multiple Devices: If you are requesting shipment of an additional device for a patient that already has a gateway at home (e.g. the prior device was ordered one month before), include both a “fulfillment_request” object and the Gateway Id for the existing Gateway in the “hardware_uuid” field. This will let our fulfillment team know they should NOT send another gateway with the second device shipment. Note, if multiple devices are requested simultaneously, our fulfillment team will automatically link all requested devices to the same Gateway at the time of shipment.

For all requests, the Device Name must exactly match the name of a Device Type associated with your account. You can get a list of valid Device Names from the hwi-device-types endpoint (see our Redoc Documentation for specific details). For reference, our standard list of Devices are shown here, though not all may be associated with a given account:

*Small BPM Cuff = 22-32 cm. Large BPM Cuff Range = 22-45 cm.

The “patient” object in the Activation Request is optional, but if it is included, a patient-specific “external_id” field is required and will be included in all Webhook callbacks associated with the newly created HWI Device (see above). We recommend Clients use a unique identifier related to the Patient object in their own systems for the “external_id” value to easily link future data to specific Patients in their systems.

The other patient fields (for example, “name” and “phone_number”) are optional, but can useful for Tenovi Customer Service to use in the event they need to troubleshoot any device issues with a patient directly. Note, these values are linked to a single Patient object in our database, which is uniquely identified by the “external_id” value used during Device activation. As a result, if you edit the optional fields of a Patient object, those fields will be updated for all Devices that are linked to a Patient object with the same external_id.

Any value entered in the “physician” field of the “patient” object will be forwarded to our fulfillment team (if a fulfillment_request is included with the Device Activation request) to allow for any per-provider shipping customization.

Example json payload data both with and without a nested fufillment_request are shown here:

{

  “device”: {

    “name”: “Tenovi BPM”,

    “hardware_uuid”: “123456789100”

  },

  “patient”: {

     “external_id”: “12345678-1234-12345678”,

     “phone_number”: “123-456-7890”,

     “physician”: “Dr. Jones”

  }

}

{

  “device”: {

    “fulfillment_request”: {

      “shipping_name”: “Patient One”,

      “shipping_address”: “123 Street”,

      “shipping_city”: “Townsville”,

      “shipping_state”: “CA”,

      “shipping_zip_code”: “12345”,

      “client_will_fulfill”: false,    

      “notify_emails”: “test@email.com”,

      “require_signature”: false,

    },

    “name”: “Tenovi BPM”,

    “hardware_uuid”: null

  },

  “patient”: {

     “external_id”: “12345678-1234-12345678”,

     “phone_number”: “123-456-7890”,

     “physician”: “Dr. Jones”

  }

}

Retrieving Gateway Information

Once a HWI device is activated, you may retrieve useful information for the linked Gateway, such as the firmware version, the last time the Gateway connected to our servers, and the cellular signal strength of the Gateway (a signal strength value of 30 is excellent, while a signal strength value of 10 is poor). Simply issue a GET request to the following endpoint:

/hwi/gateway-info/{gateway_id}/

The Gateway ID is the Hardware UUID value returned in the Device object for a HWI Device, and it should be a 12-digit hexadecimal string with no hyphens or separating characters (e.g. 1234abcd5678).

Unlinking Gateways from HWI Devices

In order to deactivate a HWI device or re-use the attached Gateway with another HWI Device, you must first either delete the HWI device or Unlink the Gateway. As HWI Devices with a Fulfillment Request cannot be deleted once that Request has been fulfilled, it is recommended to use the unlink-gateways endpoint to deactivate devices, as it is guaranteed to always succeed:

/hwi/unlink-gateway/{hwi_device_id}/

To use this endpoint, you must perform a GET request with the HWI Device id included in the URL. If it is successful, the HWI Device object will be returned with the hardware_uuid field of the nested Device object set to null.

Retrieving Measurements

If data is either missed or improperly handled by the Measurement Webhook, or a client simply wants to validate the data in their system with the data stored by Tenovi, two Measurement endpoints are available to fetch measurement data on request. The endpoints are:

1)  /hwi/hwi-devices/{hwi_device_id}/measurements/

2)  /hwi/patients/{patient_external_id}/measurements/

Optional Query Parameters:

metric__name: string

created__gte: ISO 8601 timestamp in UTC (i.e. YYYY–MM–DDTHH:MM:SSZ)

created__lt: ISO 8601 timestamp in UTC (i.e. YYYY–MM–DDTHH:MM:SSZ)

timestamp__gte: ISO 8601 timestamp in UTC (i.e. YYYY–MM–DDTHH:MM:SSZ)

timestamp__lt: ISO 8601 timestamp in UTC (i.e. YYYY–MM–DDTHH:MM:SSZ)

Measurement Response format:

[

{

“metric”: “string”,

“device_name”: “string”,

“hwi_device_id”: “string”,

“patient_id”: “string”,

“hardware_uuid”: “string”,

“sensor_code”: “string”,

“value_1”: “string”,

“value_2”: “string”,

“created”: “2019-08-24T14:16:18Z”,

“timestamp”: “2019-08-24T14:15:22Z”,

“timezone_offset”: -2147483648,

“estimated_timestamp”: false,

“filter_params”: { }

}

]

Notes:

The response data fields are identical to those sent in the Measurement Webhook POST requests (see above).

For Endpoint #1, all measurements for a given HWI Device are returned. The hwi_device_id must be included in the URL.

For Endpoint #2, all measurements for a given Patient ID (optionally set during Device Activation) are returned. The patient_external_id must be included in the URL. Note, uniqueness is not enforced for this field. All measurements from all devices associated with a patient with the given External ID will be returned.

The optional query parameters allow the request to be filtered by metric name (metric__name = blood_pressure, temperature, perfusion_index, weight, pulse, glucose, or spO2) or timestamp date greater than or equal to (timestamp__gte) or less than (timestamp__lt) a given timestamp in UTC. Note, each query parameter includes a double-underscore. This must be included for the filter to function properly. An example URL with a query parameter is:

/hwi/patients/12345/measurements/?metric__name=glucose

Setting Device Properties

For all devices, you may add user-defined key-value properties to individual devices using the following endpoint:

/hwi/hwi-devices/{hwi_device_id}/properties/

Some devices have special, Tenovi-defined properties that you can use to control certain device parameters. For example, the Step Goal value displayed on the Tenovi Watch can be modified by setting the value of the “step_goal” property. The full list of these Tenovi-defined properties can be found on our Device Overview page. 

Note, for these special, Tenovi-defined properties, the “synced” field (returned on GET requests to the above update) can be used to identify when the property value has been synchronized onto the physical device.

Viewing Hardware UUID Logs

To view change logs for the hardware_uuid field of the nested device object in a hwi-device, you may use a Get request on the following endpoint:

/hwi/hardware-uuid-logs/

Optional Query Parameters:

object_id: string

search: string

The query parameters shown above will allow you to filter by the hwi-device-id (using the object_id parameter) or search by a given hardware_uuid (using the search parameter). This can be useful for customer service or system auditing.

Requesting Supplies

Note, this feature must be enabled separately from the HWI Device endpoints described above, though the same authentication method (an API Key generated on the Tenovi dashboard) should be used. The detailed Redoc Documentation for this feature can be found here. Please contact your Account Representative to enable this feature.

Once enabled, use the following endpoint to request, list, and cancel pending Supply Requests:

/devices/supply-requests/

To request a specific supply, you must use the exact “supply_name” parameter, as provided by your account representative in the json payload, along with the shipping information for where you want the supply to be sent. Then, once a Request is fulfilled, you will automatically be billed for the item at the end of your month. You can view all pending invoices on your Tenovi dashboard.

We recommend you include the Gateway ID associated with the patient for whom you are requesting supplies in each request. This will help ensure that the proper supply type is sent to that patient based on their activated devices. For example, some glucometer strips only work with a certain glucometer type. Our fulfillment team will be able to look this information up by Gateway ID when completing a request, if it is included.

Authorization Failed (403 Error)

This error occurs if the API keys supplied are invalid or expired. Please double check your API keys or create a new one via the Client Dashboard.

Endpoint Does Not Exist (404 Error)

This error occurs if the endpoint you are requesting does not exist within the Tenovi API. Please verify the endpoint from our detailed Redoc Documentation and ensure you are using the appropriate CLIENT_DOMAIN value in your URL. You can obtain the correct CLIENT_DOMAIN value from the Client Dashboard.

Device With This Gateway ID/Sensor Code Already Exists

This error occurs when Activating/Requesting a new Device, and the type of device being activated/requested (e.g., scale, bpm, etc.) is already connected to a Gateway with the supplied Gateway ID. Gateways can only have one device of each type (scale, bpm, etc.) connected to them. Please ensure the Gateway ID supplied is correct and verify there are no other Devices of the same type connected to that Gateway on the Client Devices Dashboard.