Skip to content
Tenovi Docs

Activating/Requesting Devices

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

/hwi/hwi-devices/

Workflow for New 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 API Reference for specific details).

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.

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.

How the Patient Receives a Device

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 or IMEI is known)
  2. Devices need to be shipped to the patient by a client’s internal staff
  3. Devices need to be shipped to the patient from Tenovi (additional charges may apply for this service).

Devices Given to Patient On-Site

For Use Case #1: The nested Device object in the Activation Request must include the Gateway ID (for Gateway-Connected devices) or the IMEI (for Direct-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.

Devices Shipped to Patient

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.

Multiple Devices for a Single Patient

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.

Device Names & Sensor Codes

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 API Reference for specific details).

For reference, our standard list of Devices are shown here, though not all may be associated with a given account:

Device NameSensor CodeHardware UUID (if included)
Tenovi BPM – S10Gateway ID
Tenovi BPM – L10Gateway ID
Omron BPM10Gateway ID
Omron Wrist BPM10Gateway ID
Tenovi Pulse Ox11Gateway ID
Tenovi Glucometer12Gateway ID
Trividia Glucometer12Gateway ID
Tenovi Scale13Gateway ID
Tenovi Thermometer14Gateway ID
Tenovi Peak Flow Meter17Gateway ID
Tenovi Pillbox21Gateway ID
Tenovi Cellular BPM – S IMEI
Tenovi Cellular BPM – L IMEI
Tenovi Cellular Glucometer IMEI
Tenovi Cellular Scale IMEI
TeleRPM BPM IMEI
TeleRPM Scale IMEI

The Patient Object

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

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 Payloads

Without a Fulfillment Request

{
  "device": {
    "name": "Tenovi BPM",
    "hardware_uuid": "123456789100"
  },
  "patient": {
     "external_id": "12345678-1234-12345678",
     "phone_number": "123-456-7890",
     "physician": "Dr. Russell"
  }
}

With a Fulfillment Request

{
  "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. Russell"
  }
}

Example Response for a Device Request

[
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "Connected",
    "connected_on": "2024-08-24T14:15:22Z",
    "unlinked_on": "",
    "last_measurement": "2024-12-24T14:15:22Z",
    "device": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "fulfillment_request": {
        "created": "2024-08-24T14:15:22Z",
        "shipping_status": "DE",
        "shipping_name": "Patient One",
        "shipping_address": "123 Street",
        "shipping_city": "Townsville",
        "shipping_state": "CA",
        "shipping_zip_code": "12345",
        "shipped_on_behalf_of": "",
        "shipping_tracking_link": "http://example.com/tracking_url/",
        "ship_gateway_only": false,
        "require_signature": true,
        "shipped_on": "2024-08-24T14:15:22Z",
        "delivered_on": "2025-08-24T14:15:22Z",
        "requested_by": "",
        "client_notes": "",
        "notify_emails": "",
        "fulfilled": true,
        "client_will_fulfill": false,
        "flagged_by_client": false
      },
      "created": "2024-08-24T14:15:22Z",
      "name": "Tenovi BPM - L",
      "hardware_uuid": "123412341234",
      "sensor_code": "10",
      "sensor_id": "",
      "shared_hardware_uuid": false
    },
    "patient_id": "12345678-1234-12345678",
    "patient_phone_number": "123-456-7890",
    "patient": {
      "external_id": "12345678-1234-12345678",
      "name": "Patient One",
      "phone_number": "123-456-7890",
      "email": "user@example.com",
      "physician": "Dr. Russell"
      "clinic_name": "",
      "care_manager": "",
      "sms_opt_in": true
    }
  }
]