Skip to content
Tenovi Docs

Patients Overview

The patient object is the stable identity layer of a Tenovi integration. Build your integration around it from the start and patient data stays consistent across every device, survives gateway replacements, and validates shipping addresses before anything ships.

This page explains why the patient object matters and how to design around it. For the endpoint reference, field table, and payloads, see Patients Object. For moving an existing integration onto the patient object, see Migrating to the Patient Object.

Build patient-first

Section titled “Build patient-first”

Create the patient once as its own record, keyed by your external_id, then reference that external_id when you activate devices. The patient exists independently of any device. Every device you link points back to the same record, and updating that record updates it everywhere.

This is the model to build on. The patient is a first-class record in your integration, not data hanging off a device. That single record is what gives you consistent patient data across devices, address verification before shipping, and webhook linkage that survives hardware changes. The rest of this page covers each of those.

Why external_id is the spine

Section titled “Why external_id is the spine”

The external_id is your identifier for a patient, chosen from your own system. It is the single most important field in a Tenovi integration, because it is the one identifier that does not change.

Hardware identifiers do change. A hardware_uuid is tied to a physical Gateway, and when a Gateway is replaced, that value changes. Any logic keyed to hardware breaks at replacement time.

The external_id does not move. It is the patient_id returned in both measurement and fulfillment webhooks, so it is how you tie inbound data back to a patient in your system, regardless of what happens to the hardware underneath.

Choose a stable, unique value from your own records for external_id. Do not derive it from hardware, and do not reuse it across patients.

What the patient object gives you

Section titled “What the patient object gives you”

One record, every device. A patient record is shared by every HWI Device linked to the same external_id. Update the record once and the change applies across all of that patient’s devices. There is no per-device copy to keep in sync.

Address verification before shipping. Supply a full address (address, city, state, zip_code) on the patient record and Tenovi verifies it immediately, returning the result in address_status. Catching an invalid address here means resolving it before a device ships, rather than working with a Client Action Required webhook through subsequent API calls or in the Resolution Center in the Tenovi Web App after fulfillment has already stalled.

Stable webhook linkage. Because the external_id flows through as patient_id on every webhook, your inbound measurement and fulfillment handling stays correct even when gateways are replaced or unlinked.

Designing your integration

Section titled “Designing your integration”

Starting a new integration. Build patient-first. Create the patient record first, then activate devices against its external_id. The Patients reference has the create and update calls; the migration guide Part 2 shows the create-then-activate flow end to end.

Already integrated. If you activate devices with an external_id today, you already have patient records, since activation creates a bare one automatically. They are just unpopulated. The migration guide walks through backfilling them and moving to a patient-first activation flow.

A note on the optional external_id

Section titled “A note on the optional external_id”

Currently, external_id is optional when activating a device. However, we highly recommend you supply an external_id for your integration.

A device activated with no external_id has no stable patient identity behind it, which forfeits shared records, address verification on the patient object, and durable webhook linkage. Treat external_id as effectively required in your own integration, even though the API permits its absence.

Section titled “Related pages”