Bulk Unlinking Devices

Device audits, patient unenrollment, and hardware reclamation all produce the same task: unlink many HWI Devices in one pass. This recipe covers how to build an accurate list of devices, execute the unlink safely, and verify the result.

The process involves:

1. Build a list of HWI Device IDs, either from a CSV export in the Tenovi web app or from a filtered GET /hwi/hwi-devices/ query.
2. Loop through that list, calling GET /hwi/unlink-gateway/{hwi_device_id}/ once per device.
3. Re-query the affected Gateways to confirm they are fully cleared.

Download AI Prompt for this Recipe

Rather than a code sample you would need to adapt, the prompt below gives an AI coding assistant everything it needs to generate a working script in the language of your choice, scoped to your account and your list. Copy it into the assistant of your choice. It will ask you a few questions before it writes anything.

Never paste a live API key into an AI assistant. The prompt leaves the key as a placeholder and instructs the assistant to read it from an environment variable or your existing secret store at runtime.

Have the assistant build a dry run mode that prints the target list without calling the unlink endpoint, and run that first.

Download AI Prompt for Bulk Unlinking Recipe

Before You Start

You will need an active API key and your Client Domain. All requests are made against https://api2.tenovi.com/clients/{CLIENT_DOMAIN}/hwi/ over HTTPS. See API URL Config and Client Domain for details.

Unlinking takes effect immediately. Data transmission stops and connection fees stop at the moment the call succeeds. There is no grace period and no scheduled effective date.

A Gateway is only reusable when every device on it is unlinked. One Gateway can carry multiple HWI Devices. Unlinking two of three leaves the Gateway occupied and unavailable for a new patient. This is the most common way a bulk unlink appears to succeed while leaving hardware stranded.

The call is a GET but it changes state. Treat it accordingly. Browser prefetch, proxy caching, retry wrappers, and rerunning a saved request collection can all fire it again without you intending to.

Reruns are safe. Calling unlink-gateway against a device that is already unlinked returns 200. A partially completed batch can be rerun from the top without additional effect.

Unlinking is a one way door

An unlinked HWI Device cannot be reactivated. To put the same Gateway back into service you must activate a new HWI Device, which generates a new hwi_device_id. Any system keyed to the old ID needs a mapping update. Measurement data already collected is retained and remains accessible. Unlinking does not delete history.

Step 1 - Build the List of Devices to Unlink

You need the hwi_device_id of every device in scope. There are two ways to get them.

Option A: Export from the Tenovi Web App

The Devices screen in the Tenovi web app exports to CSV. For most audits this is the fastest path, and it lets someone outside engineering assemble and review the list before handing it over to execute.

The export includes HWI Device IDs alongside patient IDs, Gateway IDs, and date timestamps, so you can filter and cross reference in a spreadsheet without writing any code. Narrow it down to the devices in scope, then use the resulting HWI Device ID column as your input list.

Because the export carries both the patient ID and the Gateway ID on every row, it is also the quickest way to check whether a Gateway has other devices attached before you unlink anything. Sort by Gateway ID and look for duplicates.

Option B: Query hwi-devices Directly

Filter server side rather than pulling your full account and filtering locally.

GET /clients/{CLIENT_DOMAIN}/hwi/hwi-devices/?device__hardware_uuid={gateway_uuid}&page=1&page_size=100

Paginate or you will get a partial list

Requests to hwi-devices without ?page= are truncated at 1,000 results. On a large account this silently returns a subset, and a bulk unlink built from that subset will look complete when it is not. See the Pagination Guide.

Useful Query Parameters

Parameter	Description
device__hardware_uuid	Filter to devices attached to a specific Gateway. Note the double underscores.
device__hardware_uuid__iexact	Case insensitive match on the Gateway UUID.
patient__external_id	Filter to devices assigned to a specific patient. Note the double underscores. This is the query parameter form of the patient.external_id response field (see the Patients Object).
properties__key	Filter by a Device Property key. See Device Properties.
properties__value	Filter by a Device Property value.
search	Free text search term.
page	Page number within the paginated result set.
page_size	Results per page.

Note

There is no status filter on hwi-devices. The response includes devices in every state, including devices that are already unlinked. Filter those out in your own code if you want a clean count of what actually changed, though leaving them in is harmless because the unlink call is idempotent.

Choosing Your Filter: Gateway or Patient

Approach	Use when	Watch for
Gateway scoped (device__hardware_uuid)	Device audits and hardware reclamation. Guarantees the Gateway ends up fully cleared and available for reuse.	Nothing. This is the safer default.
Patient scoped (patient__external_id)	Unenrollment workflows, where the unit of work is the patient.	A device on the same Gateway may be assigned to a different patient record. The Gateway will remain occupied. Verify in Step 3.

Lead with Gateway scoped whenever the goal is to get hardware back into service. Lead with Patient scoped when working with unenrolling a patient.

Dry Run First

Output your final list of hwi_device_id values and review it before executing anything. Confirm the count matches what you expect. This is the last point at which the operation is reversible.

Step 2 - Loop the unlink-gateway Call

For each hwi_device_id in your list, send a GET request to the unlink-gateway endpoint.

GET /clients/{CLIENT_DOMAIN}/hwi/unlink-gateway/{hwi_device_id}/

curl --location 'https://api2.tenovi.com/clients/CLIENT_DOMAIN/hwi/unlink-gateway/HWI_DEVICE_ID/' \
--header 'Authorization: Api-Key API_KEY_HERE'

A successful call returns the HWI Device object with the hardware_uuid field of the nested device object set to null.

Rate limit

Each API Key is limited to 1 request per second. All requests must be made over HTTPS. At that rate a 1,000 device batch takes roughly seventeen minutes. Pace at about 1.2 seconds between calls rather than exactly 1 second, since firing on the boundary can still trigger 429 responses. Log each response so you can identify exactly where a batch stopped if it is interrupted.

Key Response Fields

Field	Notes
id	The hwi_device_id. Retired permanently once unlinked.
device.hardware_uuid	The Gateway UUID. null after a successful unlink. This is the field to check.
patient.external_id	Your identifier for the patient the device was assigned to.

A 200 does not mean this call changed anything

Because an already unlinked device also returns 200, the status code alone cannot tell you whether your call performed the unlink or found it already done. If you need an accurate count of what changed, capture the state before you run and diff against it afterward. The Hardware UUID Logs endpoint records each hardware_uuid change and is purpose built for this kind of audit.

Step 3 - Verify

Two checks, in this order.

Confirm each device is unlinked. Re-query hwi-devices for your list and confirm device.hardware_uuid is null on every record.

Confirm each Gateway is empty. For every Gateway touched by the batch, query for remaining devices:

GET /clients/{CLIENT_DOMAIN}/hwi/hwi-devices/?device__hardware_uuid={gateway_uuid}&page=1

Any device still returning with a non null device.hardware_uuid means that Gateway is still occupied and cannot be assigned to a new patient. This is the step that catches a patient scoped unlink that left hardware stranded.

Testing with Postman

If you prefer not to write a script, the Tenovi Postman collection includes the relevant calls. Postman Collection Runner can iterate a CSV of HWI Device IDs and issue one request per row.

Set the iteration delay to 1,200 milliseconds. The documented limit is 1 request per second, but Postman fires close enough to that boundary to trigger 429 responses in practice. The extra 200 milliseconds absorbs it. Run against a two or three row CSV first and confirm the response before loading the full list.

Common Issues

Issues specific to this recipe. For platform wide behavior see Common Gotchas.

404 on a device ID you believe is valid The device does not exist or belongs to a different account. The response body describes the reason. Check for a copy and paste error, a truncated ID, or an ID pulled from the wrong client domain.

The Gateway is still unavailable after unlinking Another HWI Device is still attached to it. A Gateway is only reusable once every device on it is unlinked. Query hwi-devices filtered by device__hardware_uuid to find what remains.

No devices returned when filtering by patient The query parameter is patient__external_id with double underscores. The patient.external_id form is the response field name and will not work as a filter.

You need the device back You cannot reverse an unlink. Activate a new HWI Device against the Gateway and update any mapping in your system that referenced the old hwi_device_id. Measurement history collected under the old device is retained.