Common Interfaces & Best Practices

Tenovi’s APIs provide core interfaces for managing devices, retrieving patient measurements, and accessing Gateway metadata. This guide outlines the essential endpoints you’ll need for most integrations, along with tips and best practices to avoid common pitfalls.

Note

Details of all the JSON schemas used and API endpoints available in Tenovi’s HWI API are available in our API Reference.

Core Endpoints

1. Add a New Device

Endpoint: POST /hwi/hwi-devices/

Purpose: Creates a new device record for a patient.

• Include correct device metadata and the patient identifier at creation.
• Validate that the device type is supported using the device catalogue endpoint (see #4).
• See our Activating/Requesting Devices doc for more information.

2. Unlink a Gateway or Remove a Device

Endpoint: POST /hwi/unlink-gateway/{gateway_id}/

Purpose: Unlinks devices associated with a specific Gateway.

Your application should support removing patient devices in the UI to ensure you can unenroll patients from your program and no longer be billed for inactive devices. You must call this API endpoint when a user removes a device, disassociates a patient from a Gateway, or unenrolls from your program.

• Ensure you handle confirmation states in your frontend (e.g., success/failure messages).
• Verify that the Gateway ID exists in your Tenovi account before attempting unlinking.
• See our Removing/Unlinking Devices doc for more information.
• See our Recipe for Bulk Unlinking Devices if you need to unlink many devices.

3. Retrieve Patient Measurements

Endpoint: GET /hwi/patients/{patient_external_id}/measurements/

Purpose: Retrieves a patient’s measurement history (e.g., weight, blood pressure, pulse ox).

• Ensure the patient_external_id in your system matches the Tenovi patient record exactly.
• Use date filters via query parameters where possible to minimize payload size.
• See our API Reference Doc for more information.

Note

As of April 2026, this endpoint supports pagination via ?page= and ?page_size= parameters. As of May 5, 2026, non-paginated responses will be truncated at 1,000 results. See the Pagination Guide for details.

4. Get Device & Gateway Information

Endpoint: GET /hwi/gateway-info/{gateway_uuid__iexact}/

Purpose: Retrieves device and Gateway metadata, including firmware versions, last connected date, last cellular signal strength, and whitelisted devices.

• Confirm firmware version for troubleshooting and device support.
• View cellular signal strength.
• Review devices whitelisted to the Gateway.
• See our Gateways doc for more information.

Best Practices & Common Pitfalls

Patient ID Synchronization

• Key Rule: The patient.external_id you use for Tenovi API calls must match your frontend or EHR system exactly.
• Mismatched IDs result in failed measurement queries or orphaned device records.

Handling Measurements

• Store timestamps from the measurement payload (timestamp or measurement_time) in UTC for consistency. These values include timezone offsets to allow you to calculate local time.
• If multiple device types report for the same patient, filter by measurement type to avoid confusion.

Error Handling

• Always check for 2xx responses before confirming any action to users, along with any response message for more detail.
• For 4xx responses, ensure your API keys and client domains are valid.