PatchRx Connect API (1.2.3)

While we do not expect many changes to this API, it is subject to change with notice.

The PatchRx Connect API can be used to integrate prescription adherence data generated by PatchRx devices into many applications.

We highly recommend reading through our integration guide(s). There are two of them, so the best place to start is here.

Integrating PatchRx technology can look a different depending on the intended application, so PatchRx offers two suggested paths to API integration.

Below is a chart detailing the main feature differences between the two pathways. For more detail on each path and tips for choosing between them, see each path's respective section:

• Light Integration Path
• Full Integration Path

If you're unsure which path is best, we are happy to advise!

In this pathway, the integrating partner only needs to activate and deactivate devices. After activation, the devices begin recording data that can be simply queried using device identifiers. If desired, the integrating partner can still leverage PatchRx's native inventory management system, device management, and ordering capabilities. This is the fastest way to integrate.

Consider choosing this path if some or all of the following apply...

• You need to integrate quickly
• Your application already has, or doesn't require, a robust patient/prescription data model
• Your application already has, or doesn't require, a robust frontend and UI for managing and monitoring patients and their adherence data
• Your application already has, or doesn't require, code completion tracking (typically only needed in fee-for-service applications)

Below is a high-level overview of how you might implement the PatchRx API (Light Path) in a production environment. Think of this as a typical workflow; you can adjust to your specific use-case or constraints.

Before reading through the guide's steps, it's helpful to familiarize yourself with PatchRx's data model.

Organizationally, PatchRx customers are Partners, and each partner can have 1:N Health Entity Locations (HELs). These HELs are used to represent different sites in a multi-site implementation. For the light integration, having more than 1 is optional. They are only necessary if you intend to leverage PatchRx's inventory management system. If not, it's acceptable to create a single monolithic HEL.

In this integration path, the only other objects invoved are the Devices, Gateways and PatchCaps, which are associated with HELs after shipment.

1. Obtain API key(s) and PatchRx webapp access
   Reach out to your PatchRx representative to get your API keys and webapp access. Your API requests must include the custom header:

   x-api-key: <YOUR_KEY_HERE>
   

2. Login to the webapp
   Login to the PatchRx webapp and familiarize yourself. In the Light integration path, the only relevant parts of the webapp are the Inventory and Locations tabs, as you won't be working with patients/prescriptions & billing. Here is a quick-use guide that explains how to use the webapp.

3. Test your key(s)
   You can verify that your API key is working by testing any GET endpoint with your key.

   For example, GET /all_health_entity_locations:

   curl --location 'https://external.patchrx.io/all_health_entity_locations' --header 'x-api-key: <your API key>'
   

   You should get a 200 response and a list of HELs for your partner account.

A. Inventory Management System setup (optional)

If your implementation doesn't require multi-site inventory managment, skip to section B below.

PatchRx's software has a built-in inventory management system. This system enables partners to monitor inventory levels across their health entity locations, track distribution rates, and conduct periodic audits and updates.

The IMS is built around health entity locations (HELs). Inventory flows as follows:

• Devices are added to an HEL's inventory account upon shipment
• Devices are removed from an HEL's inventory account upon activation
• Devices are re-added to the HEL's inventory account upon deactivation, unless they are marked as lost
  • note: this only applies to Gateways, as PatchCaps are disposable and are never added back to HEL inventory

System setup

If you plan to leverage this system, you'll need to create health entity locations for each site where you'd like to track inventory.

• You can check which HELs already exist for your partner by calling GET /all_health_entity_locations
• To Create additional Health Entity Location(s), use the POST /health_entity_location endpoint to create any new locations
• See the Health Entity Locations section for all HEL-related capabilities

Managing and viewing inventory

In the event that you transfer inventory between health entity locations, or if inventory is lost/destroyed, you'll need to use API calls to keep the PatchRx IMS up to date.

(calls to view and manage inventory coming soon)

B. Order inventory

Inventory can be ordered via the PatchRx webapp inventory tab.

1. Click "Order demo units" in the "Actions" block
2. Complete the modal, select shipping & payment method, and place the order

Note: If the actions block is not visible, reach out to your PatchRx representative to enable & configure ordering for your account.

In production, users will instead use the "Order inventory" button to place orders for cases of inventory rather than individual demo units.

Once you have devices, all that's needed to begin receiving data from them is activation via the API and physical setup.

• Gateways must be activated and deactivated via API upon enrollment and discontinuation respectively in order to properly manage costs
• PatchCaps do not require API activation (only physical setup/activation)

To get devices online and request their data, simply follow steps 1-4 below.

1. Activate the Gateway upon distribution: PUT /activate_gateway (coming soon, see note)
2. (if using IMS) Mark PatchCap as distributed upon distribution: PUT /patchcap_distributed (coming soon, see note)
3. Setup the devices when ready: device instructions here
4. Retrieve PatchCap data after using devices: GET /patchcap_data (coming soon, see note)

Note: These endpoints are not yet live, but can be brought online in short order if you are interested in the Light integration path.

To discontinue connectivity-related billing, Gateways must be deactivated when they are no longer used. However, they are reusable, provided that the patient returns them with their accessories and they are in clean, working order.

• If the patient returns a reusable Gateway, call PUT /deactivate_gateway with returned = true, which will:
  • Deactivate the Gateway, disabling its SIM and related billing
  • Add the Gateway back to the original HEL's inventory account (only applicable if using PatchRx IMS)
• If the patient does NOT return a reusable device, call PUT /deactivate_gateway with returned = false, which will:
  • Deactivate the Gateway, disabling its SIM and related billing
  • Mark the Gateway as lost (only applicable if using PatchRx IMS)

If a patient returns a device that is not reusable (missing accessories, etc.), PatchRx has a recycling & rebate program. Reach out to your PatchRx representative for more information.

Note: These endpoints are not yet live, but can be brought online in short order if you are interested in the Light integration path.

In this pathway, the integrating partner will create patients and prescriptions in the PatchRx environment before associating and assigning devices to them. This is a more involved integration pathway, but enables use of the PatchRx webapp for monitoring and managing patients and their devices. Additionally, it allows for automated code completion tracking.

Consider choosing this path if some or all of the following apply...

• You have more time for integration
• You would like the ability to manage patients via the PatchRx Webapp
• You would like to be able to monitor patient's prescription adherence and related metrics via the PatchRx Webapp
• Your application requires devices/data to be associated with patients/prescriptions in the PatchRx environment, i.e.
  • You'd like to have parallel patient and prescription objects in PatchRx to mirror your application, OR
  • Your application doesn't have these objects at all & needs PatchRx to be source of truth for them

Below is a high-level overview of how you might implement the PatchRx API in a production environment. Think of this as a typical workflow; you can adjust to your specific use-case or constraints. Before reading through the guide's steps, it's helpful to familiarize yourself with PatchRx's data model.

Organizationally, PatchRx customers are Partners, and each partner can have 1:N Health Entity Locations (HELs). These HELs are used to represent different sites in a multi-site implementation. Patients are organized underneath HELs, as each HEL can have 0:N patients. Patients themselves can have 0:N Prescriptions and 0:N Devices (PatchCaps & Gateways). Gateways are associated with the Patient, while PatchCaps are assigned to the Patient's Prescriptions.

1. Obtain API key(s) and PatchRx webapp access
   Reach out to your PatchRx representative to get your API keys and webapp access. Your API requests must include the custom header:

   x-api-key: <YOUR_KEY_HERE>
   

2. Login to the webapp
   Login to the PatchRx webapp and familiarize yourself. Here is a quick-use guide that explains how to use it.

3. Test your key(s)
   You can verify that your API key is working by testing any GET endpoint using cURL.

   For example, GET /all_health_entity_locations:

   curl --location 'https://external.patchrx.io/all_health_entity_locations' --header 'x-api-key: <your API key>'
   

   You should get a 200 response and a list of HELs for your partner account.

Health entity locations are the key organizational block in PatchRx's data model. Patients and inventory are organized underneath them, and webapp user permissions are scoped by association with them (for more on permissions, see here).

For multi-site implementations, we recommend creating health entity locations for each physical site, as it makes managing patient populations easier and facilitates the use of PatchRx's inventory management system. The inventory management system enables partners to monitor inventory levels across their health entity locations, track distribution rates, and conduct periodic audits and updates.

Inventory flows as follows:

• Devices are added to an HEL's inventory account upon shipment
• Devices are removed from an HEL's inventory account upon activation
• Devices are re-added to the HEL's inventory account upon deactivation, unless they are marked as lost
  • note: this only applies to Gateways, as PatchCaps are disposable and are never added back to HEL inventory

If you plan to leverage this system, or would like to cleanly segment patient populations by location, you'll need to create health entity locations for each respective location. For your integration, you can manage this manually or setup a trigger to create new locations in PatchRx upon creation in your application.

If you don't wish to leverage the benefits of multiple HELs, you can proceed with a single default HEL for organizing all patients and inventory.

A. Create health entity locations (if needed)

• You can check which HELs already exist for your partner by calling GET /all_health_entity_locations
• To Create additional Health Entity Location(s), use the POST /health_entity_location endpoint to create any new locations
• See the Health Entity Locations section for all HEL-related capabilities

B. Order inventory

Inventory can be ordered via the PatchRx webapp inventory tab.

1. Click "Order demo units" in the "Actions" block
2. Complete the modal, select shipping & payment method, and place the order

Note: If the actions block is not visible, reach out to your PatchRx representative to enable & configure ordering for your account.

When your integration is in production, users will instead use the "Order inventory" button to place orders for cases of inventory rather than individual demo units.

C. Viewing & managing inventory

In the event that you transfer inventory between health entity locations, or if inventory is lost/destroyed, you'll need to use API calls to keep the PatchRx IMS up to date.

(calls to view and manage inventory coming soon)

Once you have set up your health entity locations, ordered inventory, and that inventory has shipped, the inventory chart on the inventory tab should be updated to reflect that those units are now in stock and ready to be associated with patients / assigned to prescriptions.

PatchRx has two types of devices: PatchCaps and Gateways.

Gateways are relay devices that sync data from PatchCaps and send it to the cloud via cellular connection. It is required to associate Gateways with patients, as it enables the device's SIM. If it's not associated with a patient, the device is inert and will not sync data.

PatchCaps are the sensors responsible for actually measuring the bottle openings and closings. To support polypharmacy situations, they are assigned to patient's prescriptions.

To get a patient set up for monitoring, you'll need to do the following in order:

1. Create their patient record (requires: name, dob, health entity location, timezone)
2. Create their prescription record(s) (requires: RxCUI or NDC) or DIN)*
3. Associate Gateway with patient (requires: Gateway serial number)
4. Assign PatchCap to prescription (requires: PatchCap serial number)

Because PatchCaps are disposable and have a limited lifespan (>120 days), it will be necessary to repeat step 4 each time they get a replacement. If their prescription changes, it will be necessary to repeat steps 2 and 4.

We typically recommend completing steps 1-4 all at once upon patient enrollment in your application, but in some cases partners may make the calls separately.

Note: throughout these docs, we use "associate" to refer to the creation of a relationship between device and patient. "Assign" is used to refer to the creation of a relationship between a device and a prescription.

1. Creating Patients

• Call POST /patient
• You can optionally supply your own external identifier in the id field
• For additional patient-related endpoints, see the patients section

2. Creating Prescriptions

• For each of the patient's to-be-monitored prescriptions, call POST /prescription
• You can also pass in your own external prescription ID if desired, or let PatchRx generate one
• For additional prescription-related endponts, see the prescriptions section

3. Associate Gateway

• When the Gateway is distributed to the patient, call PUT /associate_gateway to associate it with them

4. Assign PatchCap

• When the PatchCap is distributed to the patient, call PUT /assign_patchcap to assign it to their respective prescription
• Assignment to a patient's prescription is required for data to flow properly
• Assignment to a patient's prescription will also associate the PatchCap with the patient

Once steps 1-4 are complete, the patient only needs to plug in their Gateway, affix their PatchCap, and pull its activation tab (see setup). From thereon, the sytem should passively record their openings and make that data available via API.

Currently, opening events are retrieved via a single API call: GET /bottle_opens, which will return a list of a given patient's opening events, tagged with the prescription ID, medication name, device serial, and event time.

The full integration path does allow for patient monitoring via the PatchRx webapp.

• From the patients tab, find and click on a patient
• On their page, you can view time series data for openings and high level metrics across any desired timeframe, which you can set via the "Metrics Start" and "Metrics End" boxes

Temporarily Disabled. In the future, GET /patient_patchcap_connectivity will provide heartbeat-driven connectivity metrics (e.g., "online" vs. "offline").

A small portion of patients will inevitably discontinue their monitoring program. In that event, it's important to clean up their PatchRx records to facilitate device reuse and avoid unnecessary billing charges.

Gateways are reusable (provided they still have their accessories and are in clean, working order).

If the patient returns a reusable device, use the PUT /unassociate_gateway call to unassociate the Gateway from the discontinuing patient and disable its SIM. Then use PUT /patient to update the patient's state to "archived". These calls will:

• Mark the patient as "archived" (important for analytics, billing, etc.)
• Disable the Gateway's SIM and related billing
• Free up the Gateway for re-association with another patient

If the patient does NOT return a reusable device, simply use PUT /patient to update the patient's state to "archived". This will:

• Mark the patient as "archived" (important for analytics, billing, etc.)
• Disable the Gateway's SIM and related billing
• Mark the Gateway as lost for inventory accounting purposes

If a patient returns a device that is not reusable (missing accessories, etc.), PatchRx has a recycling & rebate program. Reach out to your PatchRx representative for more information.

Permissioning

API connections have full partner-scoped permissions, meaning they can create, update, and read from any entities created underneath their partner.

Webapp users have health-entity-location-scoped permissions, meaning their abilities are limited by which health entity locations they're associated. For more detail, see the users endpoints.

External IDs

Some entities support creation and reference using external identifiers. This means that you can use your organization's unique identifiers in lieu of PatchRx's generated identifiers. Doing so is optional, and PatchRx will generate unique identifiers if they are not provided. Currently, this is supported for health entity locations, patients, and prescriptions.

PatchRx uses a tiered structure for grouping patients. Organizations using the API are Partners. Each partner may have 1:N Health Entity Location(s).

These locations are used for managing patients and inventory in multi-site applications.

The patients endpoint is used for creating and managing parallel representations of patients.

The prescriptions endpoint is used for creating and managing parallel representations of patient's prescriptions.

Patients can have multiple prescriptions, and each prescription can have multiple PatchCaps as they're used and replaced.

The device endpoints are used for managing device <> patient, device <> prescription.

There are two types of devices, PatchCaps and Gateways.

PatchCaps are the actual pill bottle sensors, and are assigned to a patient's prescription. Gateways forward data from PatchCaps to the cloud, and are associated with the patient.

To get a patient's devices set up & ready to stream data, check out the relevant integration guide section:

• Full integration
• Light integration

Be sure to review the respective sections related to device return as well.

Note: PatchCaps can be associated with the patient, but PatchCap<>patient association is a weak relationship -- data is only reported from PatchCaps that have been assigned to a given prescription. For the purposes of the external API, it may make sense to skip PatchCap association and go straight to assignment.

The data endpoints are used for interfacing with sensor metadata and event data.

The users endpoints are used for creating, updating, and managing the permissions of PatchRx webapp users.

PatchRx webapp user permissions are scoped by their health entity location associations, so users are only able to see patients that are attached to the same health entity locations as themselves.

All users are able to create new users within the webapp, but they are only able to associate them with a subset of their own health entity location associations.

NOTE: Under construction

The orders endpoints is used for retrieving order information.

The utilities endpoints are for miscellaneous or integration-related usage.