Patients Object

The hwi-patients endpoint allows you to create and manage patient records independently of device activation. Patient records created here are shared across all HWI Devices linked to the same external_id, making this the recommended way to manage patient data at scale.

Note

This endpoint was added in October 2025. Prior to this, patient records could only be created as a nested object during device activation via hwi-devices. Both methods remain supported.

However, it is highly recommended to make use of independent API calls as outlined on this page to ensure your patient records in Tenovi are kept up to date.

The Patient Object

Field	Type	Required	Description
external_id	string	Yes	Your unique identifier for this patient. Used as the lookup key for all GET, PUT, PATCH, and DELETE requests.
name	string	No	Patient’s full name.
address	string	No	Street address. Required for address verification.
city	string	No	City. Required for address verification.
state	string	No	State. Required for address verification.
zip_code	string	No	ZIP code. Required for address verification.
phone_number	string	No	Used by Tenovi support for service requests and optional SMS notifications.
email	string	No	Not validated. Used by Tenovi support for service requests.
physician	string	No	Forwarded to the fulfillment team for per-provider shipping customizations (charges may apply). Contact your Customer Success Manager for more information.
clinic_name	string	No	Clinic or organization name.
care_manager	string	No	Name of the assigned care manager.
sms_opt_in	boolean	No	Set to false if the patient has not consented to SMS messages. Defaults to true.
confirm_address	boolean	No	Set to true to override Tenovi’s internal address verification.
address_status	string	Read-only	Returns Verified or Invalid after address verification.
address_verified_by	string	Read-only	Indicates the system used to verify the address.

Create a Patient

POST https://api2.tenovi.com/clients/{CLIENT_DOMAIN}/hwi/hwi-patients/

The external_id field is required and must be unique across your account. If you submit a POST with an external_id that already exists, the request will be rejected.

Example request:

{
  "external_id": "patient-001",
  "name": "Patrick Smith",
  "address": "18023 Sky Park Cir Suite H2",
  "city": "Irvine",
  "state": "CA",
  "zip_code": "92614",
  "phone_number": "18005935468",
  "email": "psmith@example.com",
  "physician": "Dr. Ian Russell",
  "clinic_name": "Flint Rehab",
  "care_manager": "Jordan Benoit",
  "sms_opt_in": true
}

Example response:

{
  "external_id": "patient-001",
  "name": "Patrick Smith",
  "address": "18023 Sky Park Cir Suite H2",
  "city": "Irvine",
  "state": "CA",
  "zip_code": "92614",
  "phone_number": "18005935468",
  "email": "psmith@example.com",
  "physician": "Dr. Ian Russell",
  "clinic_name": "Flint Rehab",
  "care_manager": "Jordan Benoit",
  "sms_opt_in": true,
  "address_status": "Verified",
  "address_verified_by": "internal",
  "confirm_address": false
}

Address Verification

When a full address is provided (address, city, state, zip_code), Tenovi automatically attempts to verify it immediately when creating or updating a patient record. The result is returned in the address_status field.

Address Status	Meaning
Verified	Address passed internal validation.
Invalid	Address could not be verified. Fulfillment requests using this address may trigger a Client Action Required webhook.

If you have confirmed the address is correct despite the Invalid status (e.g., a rural address that fails automated lookup), set confirm_address: true to bypass verification.

{
  "external_id": "patient-001",
  "address": "18023 Sky Park Cir Suite H2",
  "city": "Irvine",
  "state": "CA",
  "zip_code": "92614",
  "confirm_address": true
}

Retrieve All Patient Records

GET https://api2.tenovi.com/clients/{CLIENT_DOMAIN}/hwi/hwi-patients/

This endpoint is always paginated. It returns a paginated response object whether or not ?page= is included, wrapping results in count, next, previous, and results fields. Use page to move through the pages and page_size to control the number of records per page.

{
  "count": 255,
  "next": "https://api2.tenovi.com/clients/{CLIENT_DOMAIN}/hwi/hwi-patients/?page=2&page_size=100",
  "previous": null,
  "results": [
    { "external_id": "patient-001", "name": "Patrick Smith", ... },
    // More patient records in array
  ]
}

Follow the next URL until it returns null to retrieve every patient record. See the Pagination Guide for full usage and migration notes.

Retrieve a Single Patient Record

Use the patient’s external_id as the lookup key in the URL path. The lookup is case-insensitive.

GET https://api2.tenovi.com/clients/{CLIENT_DOMAIN}/hwi/hwi-patients/{external_id}/

Update a Patient

Use PUT for a full update or PATCH for a partial update. Both use external_id as the lookup key.

PATCH https://api2.tenovi.com/clients/{CLIENT_DOMAIN}/hwi/hwi-patients/{external_id}/

{
  "external_id": "patient-001",
  "name": "Patrick Smith",
  "phone_number": "7144185658",
  "sms_opt_in": false
}

Note

Updating a patient record here will update that patient’s data across all HWI Devices linked to the same external_id. This is the recommended way to keep patient data consistent across multiple devices.

If you update the address, Tenovi will re-run address verification automatically unless confirm_address: true is included.

Delete a Patient

DELETE https://api2.tenovi.com/clients/{CLIENT_DOMAIN}/hwi/hwi-patients/{external_id}/

Returns 204 No Content on success.

Caution

Deleting a patient record does not deactivate linked HWI Devices, but those devices will no longer have patient data associated with them.

Relationship to HWI Devices

Patient records created via hwi-patients are the same records used in the nested patient object on hwi-devices. The external_id is the shared key.

Activating a Device

If a patient record already exists, include the external_id in the nested patient object when activating a device. Tenovi will link the device to the existing patient rather than creating a duplicate.

{
  "device": {
    "name": "Tenovi BPM - Wide Range",
    "hardware_uuid": "123412341234"
  },
  "patient": {
    "external_id": "patient-001"
  }
}

Patient Data in Webhooks

The patient_id field in both measurement and fulfillment webhooks maps to the patient’s external_id. This is the stable identifier you should use to link webhook data back to patients in your system - it does not change when a gateway is replaced or unlinked.

Caution

Do not use hardware_uuid to identify patients. This value changes when a Gateway is replaced. Always use hwi_device_id or patient_id (external_id) for stable patient linkage.

Common Issues

For the exact hwi-patients validation messages (400 responses) and how to resolve each, see Error Messages & Debugging.

external_id already exists Each external_id must be unique. If you receive a conflict error on POST, use PUT or PATCH to update the existing record instead, or use a GET request to check whether the patient already exists before creating.

address_status: Invalid blocking fulfillment Tenovi will flag fulfillment requests with unverified addresses, which triggers a Client Action Required webhook. Resolve this before submitting fulfillment by either correcting the address or setting confirm_address: true if you have independently verified it.

Patient data not appearing on a device If a patient was created via hwi-patients but the device was activated without a patient object, use PUT /hwi-devices/{id}/ to attach the patient by external_id. On a PUT to hwi-devices only fields within the nested patient object can be modified, so set patient.external_id to align the device with the correct patient record.

SMS opt-in default sms_opt_in defaults to true. If you have not collected explicit patient consent for SMS, set this to false at creation time.