Replacing Devices & Gateways

You can request replacements for devices and Gateways, get a list of all replacements (both requested and issued/shipped), and remove pending replacement requests using these series of endpoints.

Note

All replacements requested via API will be charged to your Tenovi account and device waranties will not apply. If you want to request a replacement under our standard device waranties, please request a replacement via the Tenovi web app.

Please see our API Reference documentation for more information on these API endpoints.

Requesting a Replacement

When you request a replacement device and/or Gateway, you can use the /hwi/hwi-replacements/ endpoint to POST your request. Using this endpoint, you can request a replacement device, Gateway, or both by providing an array of the replacements you require.

Shipping information and the device’s HWI Device ID is required for all replacement requests when done via API.

If you are requesting a replacement Gateway, Tenovi will automatically update the hardware_uuid of any HWI Devices linked to the same Gateway as the referenced HWI Device. Our system will send a Fulfillment Webhook with the updated Gateway ID when the replacement is shipped.

Note

Fulfillment Webhooks – If multiple HWI Devices were linked to the original Gateway, each will generate a fulfillment webhook with the status set to Replaced.

Ideally, if you are mapping patient data by HWI Device ID (hwi_device_id) or Patient ID (patient.external_id) the webhooks are informative only and no action is required on your part to ensure patient data flows correctly. However, if you are leaning on the IMEI/Gateway ID (hardware_uuid) you will need to ensure you update your records with the new hardware_uuid. The fields in a fulfillment webhook for a replacement contain:

• hardware_uuid: The new Gateway ID or IMEI sent as a replacement
• device_id: The old Gateway ID or IMEI that was replaced
• status: Always “Replaced” in this context

Tenovi updates the hardware_uuid when a new Gateway is shipped, not when it is delivered. We do the update at time of shipment as it is our understanding the original Gateway is not functioning and cannot send data. If you require hardware_uuid updates to occur when the new Gateway arrives, you will have to lean upon logic in your system to temporarily save the replacement webhook (sent when the device is shipped), but not update your records until your receive the delivered webhook.

Example JSON for Replacements

{
    "device_types": [
        {
            "name": "Tenovi BPM - L"
        },
        {
            "name": "Gateway"
        }
    ],
    "shipping_name": "Dr. Ian Russell",
    "shipping_address": "18023 Sky Park Circle",
    "shipping_city": "Irvine",
    "shipping_state": "CA",
    "shipping_zip_code": "92614",
    "notify_emails": "user@tenovi.com, anotheruser@tenovi.com",
    "hwi_device_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get a List of All Replacements

You can fetch a list of all replacements (those that are both already fulfilled and those that are pending fulfillment) using the GET method on /hwi/hwi-replacements/ endpoint. This returns an array of replacement requests that include information on shipping, status of the replacement, device types requested, and shipping tracking URLs.

Delete a Pending Replacement Request

You can use the DEL method on the /hwi/hwi-replacements/{id} endpoint to cancel/delete a pending replacement request, passing in the ID of the request (found using the GET method). Please note that only replacement requests that haven’t been fulfilled yet can be deleted. Once a replacement shipment leaves our warehouse we are unable to cancel/delete the request.