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, sometimes patients start but do not complete the flow. It can be incredibly helpful to remind these patients that they have an outstanding action — a process HealthEx refers to as nudging.

HealthEx offers two ways to nudge patients: we can manage it for you automatically, 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 you want to use this default.

This feature works as follows:

  • HealthEx periodically scans your project's patients for incomplete retrievals.
  • When a stalled patient is identified, we send them an email reminding them to complete the flow.
  • The email contains a Resume Link which takes the patient back exactly to where they left off, remembering everything they had done before abandoning the flow.
OAuth Limitations

If your project uses the OAuth flow, HealthEx-initiated nudges are not supported and cannot be enabled. Because an OAuth flow is stateful, HealthEx cannot launch a patient into an existing OAuth session on your behalf. If you are using OAuth, you must send customer-initiated nudges (see below).

Customer-Initiated Nudges​

Customers may prefer to manage and send nudges themselves. There are several reasons you might want to do this:

  • To send nudges from your own corporate email address or phone number, allowing you to fully customize the copy and branding.
  • To trigger the nudge flow from within your own application, providing the patient with a more deeply integrated experience.
  • If you are using the OAuth flow, you must start the flow from your own application, making this your only option.

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

Step 1: Determine Who to Nudge​

To determine which patients need a nudge, you should periodically call the Patient Flow Progress API on each of your known patients. To make this queryable, we highly recommend you do one of the following:

Once you get a response from the API, there are two common scenarios where a nudge is appropriate:

  1. Not Consented: If your records show that you requested data from this user, but the consentStatus is NOT_CONSENTED, you will likely want to nudge them to formally consent so their data can be retrieved.
  2. In Progress: If the API response contains a retrieval whose status is IN_PROGRESS, the user started to retrieve data but did not finish. You can use the createdAt field of the retrieval to decide if a nudge is appropriate. (Tip: You likely don't want to nudge very old retrievals, nor do you want to nudge a retrieval created 5 minutes ago while the user is still actively working on it!)

Step 2: Send the Nudge​

Once you have identified who to nudge, you can send that patient a notification in the format of your choice (email, SMS, in-app notification, etc.). The content of this notification is entirely up to you.

However, we strongly recommend including a Resume Link in your notification. This special link drops the user back into the retrieval flow exactly where they left off.

For example, if the user manually added two healthcare locations and then gave up, clicking the Resume Link will bring them back to a screen where those two locations are already saved. Decreasing repeat work drastically improves completion rates.

For Non-OAuth Flows​

You can easily copy the Resume Link for your project directly from the HealthEx UI:

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

If you prefer to generate the link programmatically, the structure always looks like this:

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

Simply replace {project-id} with your actual project ID.

For OAuth Flows​

You cannot include a direct link to HealthEx in your notification, because the OAuth flow must be initiated from your own application. Instead, you should include a link that directs the patient back to your app.

When the user clicks that link, your application should initiate the OAuth Authentication Flow as normal, with one small adjustment: When calling the Authorization Request (/oauth/authorize) endpoint, you must include the additional query parameter resume=true.

Once the OAuth flow launches the user into the HealthEx application, HealthEx will detect the flag and allow the user to pick up right where they left off.