Migrating to the Patient Object

This guide is for Tenovi accounts that already activate devices with a patient external_id but have never populated the rest of the patient record. It moves you to the hwi-patients endpoint as the source of truth for patient data.

• Populate a patient record once and it is shared by every device linked to that external_id.
• Supply the address during patient object creation and Tenovi will validate the address instantly.
• Usage of the dedicated patients object prepares you for future iterations of the Tenovi HWI API that will be patient-centric.

There are two parts to this guide that focus on backfilling existing records and changing your device activation workflows for new devices going forward.

Part 1: Updating Existing Patient Objects. A one time backfill that brings the patient records you already have up to date with names, addresses, and other optional fields.

Part 2: Adopting the Patient Object in Device Activation. A change to your device activation flow so every new patient record is fully populated and address verified before a device is shipped.

Most accounts work through Part 1 once, then adopt Part 2 permanently. If you do not currently send a patient external_id during activation at all, you can skip Part 1 and go straight to Part 2.

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.

Why Migrate

When you activate a device with a nested patient external_id, Tenovi automatically creates a patient object keyed to that external_id. That record exists, but it carries only the external_id. Using this workflow, every other field in the patient object is empty. There are three reasons to populate it.

Addresses are not verified before a device ships. When the shipping address lives only in your device activation call, an invalid address is not caught up front. It surfaces at fulfillment as a Client Action Required webhook, which has to be resolved by hand in the Resolution Center of the Tenovi web app or via subsequent API calls to remove and recreate the device activation. Supplying the address on the patient record instead means it is verified up front, before anything ships. See Handling Address Verification.

Patient data is scattered instead of shared. A populated patient record is shared by every HWI Device linked to the same external_id. Update it once and it is consistent across all of them. Without this, patient data lives on individual device calls and keeping it in sync is your problem to solve.

The patient object is the model future iterations of the HWI API are built around. Adopting it now means the workflow you build today carries forward. Leaving it means reworking your integration later.

The Patient Object

For the complete field reference, see the Patients endpoint documentation. The fields most relevant to this migration:

Field	Type	Required	Notes
external_id	string	Yes	Your unique identifier for the patient. The lookup key for all GET, PUT, PATCH, DELETE calls.
name	string	No	Patient full name.
address	string	No	Street address. Required for address verification.
city	string	No	Required for address verification.
state	string	No	Required for address verification.
zip_code	string	No	Required for address verification.
phone_number	string	No	Used by Tenovi support for service requests and optional SMS notifications.
sms_opt_in	boolean	No	Defaults to true. Set to false if the patient has not consented to SMS.
confirm_address	boolean	No	Set to true to override internal address verification.
address_status	string	Read-only	Returns Verified or Invalid after verification.

Note

Address verification requires the full set of address, city, state, and zip_code. A partial address is not verified.

Part 1: Updating Existing Patient Objects

Use this part when your account already activates devices with a patient external_id. The patient records exist but are unpopulated. The following steps bring these empty patient records up to date.

Step 1: Confirm You Use Patient IDs

Confirm that your current device activation flow includes a patient external_id. If it does, Tenovi has already created a bare patient record for each one, and those records are what you are about to populate.

If your activation flow does not send an external_id at all, there is nothing to backfill. Skip to Part 2.

Step 2: Update Each Existing Record

Because activation already created the record, you never need to create it here. You update it. Send a PATCH with the external_id in the URL and the optional fields in the body.

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

{
  "external_id": "patient-001",
  "name": "Patrick Smith",
  "address": "18023 Sky Park Cir Suite H2",
  "city": "Irvine",
  "state": "CA",
  "zip_code": "92614",
  "phone_number": "18005935468",
  "sms_opt_in": true
}

Use PATCH for a partial update or PUT for a full replacement. For a backfill, PATCH is usually what you want, since it only touches the fields you send.

A successful update returns the full patient record, including the read only address_status. If you supplied a full address, check that field on the response. See Handling Address Verification below.

Step 3: Confirm the Update

Updating a patient record updates that patient data across all HWI Devices linked to the same external_id. That is the point. One record, many devices, one place to keep it correct.

If you want to verify a record before or after updating it, GET it by external_id:

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

Part 2: Adopting the Patient Object in Device Activation

This part changes your go forward device activation flow. Today you likely send one call carrying device details and patient details together. Going forward you make the patient record explicit, and verify its address, before the device call.

The flow becomes two calls instead of one:

1. Establish the patient record (create it if new, update it if it already exists).
2. Run your normal device activation using that patient external_id.

The Decision Point

Before you write the patient, you need to know whether that external_id already exists on your account. A POST to hwi-patients with an external_id that already exists is rejected, so you cannot blindly create.

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

• 404 Not Found. The patient does not exist. Create it (Step 1).
• 200 OK. The patient already exists. Update it (Step 2). This is the same operation described in Part 1, Step 2.

Step 1: Create a New Patient

If the patient does not yet exist, POST the full record. Supplying the full address here triggers immediate verification, so you learn the address is good before anything ships.

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

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

The response includes the read only address_status. Check it before proceeding to activation. See Handling Address Verification.

Step 2: Update an Existing Patient

If the external_id already exists, do not POST. Update the record instead, exactly as in Part 1. Follow the steps outlined in Part 1, Step 2. The same PATCH or PUT call, the same address verification behavior, applies here.

Step 3: Activate the Device

With the patient record established and its address verified, run your normal activation flow. Reference the patient by external_id in the nested patient object so Tenovi links the device to the existing record rather than creating a duplicate.

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

See Activating a Device for the full activation reference.

Handling Address Verification

Whenever you send a full address on a POST, PUT, or PATCH to hwi-patients, Tenovi verifies it immediately and returns the result in the read only address_status field.

address_status	Meaning
Verified	Address passed validation. Safe to proceed to activation and fulfillment.
Invalid	Address could not be verified. A fulfillment request using it may trigger a Client Action Required webhook.

Catching an Invalid result here, before the device call, is the entire reason to establish the patient first. It moves address resolution out of the Resolution Center and into your integration, before anything ships. It allows you to be proactive with invalid shipping addresses and you can make corrections here and now versus during the shipping process using fulfillment webhooks.

If you have independently confirmed an address that fails automated lookup (for example a rural address), 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
}

Common Issues

external_id already exists on POST A POST with an existing external_id is rejected. This is expected. GET the record first to decide between create and update, as described in The Decision Point.

address_status: Invalid after update The address failed automated verification. Correct the address and resend, or set confirm_address: true if you have independently verified it. Resolve this before activation so fulfillment does not stall in the Resolution Center.

Update did not change data on a device Patient records are shared by external_id. If a device still shows no patient data after an update, confirm the device was activated with that external_id. If it was activated without a patient object, attach the patient with a PUT /hwi-devices/{id}/. On this call only fields within the nested patient object can be modified, so set patient.external_id to align the device with the correct patient record. See Patient data not appearing on a device.

Partial address not verified Address verification requires address, city, state, and zip_code together. If address_status comes back empty, confirm all four were sent.