Skip to main content

Nudging Patients

HealthEx makes every effort to ensure the patient data retrieval flow is easy and quick to complete. Despite this, however, sometimes patients start but don't complete the flow. It can be helpful to remind these patients that they have an action outstanding, a process HealthEx refers to as "nudging."

HealthEx offers two ways to nudge patients: we can do it for you, or you can manage it yourself.

HealthEx initiated nudges​

The default behavior for all projects is that HealthEx will manage nudging patients. No action is required on your part if this is what you want.

The feature works roughly like this:

  • HealthEx periodically scans your project's patients for incomplete retrievals
  • When a patient is identified, we send them an email reminding them to complete the flow
  • The email contains a "resume link" which will take the patient back to where they left off, remembering everything they had done before they abandoned the flow.

Important: If your project uses the OAuth flow, HealthEx initiated nudges are not supported and cannot be enabled. The reason for this is that an OAuth flow is stateful and we cannot launch the patient into an existing OAuth flow. If you're using OAuth, you will need to send nudges yourself (see below).

Customer initiated nudges​

Customers may instead want to perform nudging themselves. There are several reasons you might want to do this:

  • Ability to send nudges from your own email address or phone number, and customize the look and feel of these notifications
  • Triggering the nudge flow from within your own application may provide the patient with a more integrated experience
  • If you're using the OAuth flow, you must start the flow from your own application, so this is your only option.

If you want to send your own nudges, you should turn off the HealthEx initiated nudges in your project settings.

Step 1: Figure out who to nudge​

In order to figure out who to send nudges to, you should periodically call the Patient Flow Progress API on each of your known patients. We recommend you use either:

After getting a response, there are likely two scenarios in which you want to nudge a patient:

  1. If your own records show that you requested data from this user, but consentStatus is NOT_CONSENTED, you will likely want to nudge them to consent and then retrieve their data
  2. If the API response contains a retrieval whose status is IN_PROGRESS, this means the user started to retrieve data but did not complete the process. Again, you will likely want to nudge them to complete the retrieval. You can use the createdAt field of the retrieval to determine whether to nudge - you might not want to nudge very old retrievals, but you also might not want to nudge on a retrieval that was created minutes ago, as the user is likely still actively working on it.

Step 2: Sending the nudge​

Once you've figured out who to nudge, you can send that patient a notification in a format of your choice (email, text, etc.). The content of this notification is entirely up to you.

However, we do recommend you include a "Resume Link" in your notification. This is a link to the patient retrieval flow for your project, but it is special because it will pick up where the user left off in the flow.

For example, imagine the user manually added two healthcare locations and then gave up. Using the resume link will bring the user back in a state where those two locations are already added. This decreases the amount of repeat work users have to do, greatly improving the chances of them finishing the flow.

For non-OAuth flows​

You can copy the resume link for your project from the HealthEx UI:

  • Navigate to the Project Manager for your project
  • Click the "Add patients" button in the top right and choose "Share patient experience with QR code or link"
  • From the "Link type" dropdown at the top of the dialog, choose "Resume link"
  • Copy the link or QR code

If you want to generate the link yourself, the link always looks like this:

https://app.healthex.io/#/patient-consent/resume?studyId=<project id>

You just need to replace the project ID with your own project ID.

For OAuth flows​

You cannot include a link directly to HealthEx in your notification because you need to initiate the OAuth flow from your own application. Instead, you will want to include a link to your own application.

When the user clicks on that link, your application can initiate the OAuth Authentication Flow as normal, with one small adjustment: When calling the Authorization Request (/oauth/authorize) endpoint, you should include an additional query parameter resume=true. Once the OAuth flow launches the user into the HealthEx application, the user will pick up where they left off, just like the resume link above.