Skip to main content

Add Patients by Unique Link

HealthEx's unique patient link functionality allows you to associate an external id with a patient without needing to explicitly add them to a project.

This allows you to use your organization's own identifiers to refer to a patient, so that when the patient responds, you will be able to objectively recognize them by this unique identifier.

This guide will cover how to generate such a unique link. Once you have a link, you can send it to the appropriate patient. From the patient's perspective, their experience will be identical to using the generic patient experience link - the underlying association with the supplied external id will happen transparently.

Prerequisites​

Before you can generate a unique link, you'll need:

  • A HealthEx account
  • An active project in HealthEx (links can only be generated for active projects)
  • Valid API credentials (see Authentication for setup instructions)
  • The external id, such as MRN or member ID, that you wish to encode in the link

Identifying Your Project​

To generate a unique link for a project, you'll need the project's unique identifier:

  1. Navigate to the "Home" section in HealthEx
  2. Locate your project in the projects list
  3. Click on the project to view its details
  4. The project ID can be found in the URL: https://app.healthex.io/#/projects/{project-id}/patient-management

Example Values​

For this example, we will use the following values:

  • Project ID: 694d61c2-3f1b
  • External ID: 123-456-0000

Making the API Call​

To generate a unique link, you would make the following API call:

POST https://api.healthex.io/v1/projects/694d61c2-3f1b-4dc8/link
Accept: application/json
Authorization: Bearer <your JWT token>
{
    "externalId": "123-456-0000"
}

This API requires you to pass a JWT token to authenticate. See the Authentication guide for more info.

The response body will simply be a string, which is the unique link:

https://app.healthex.io/#/patient-consent/694d61c2-3f1b/enrollment/link?xid=123-456-000.eyjUKFNMP

That's it! You now have a unique link that you can send to your patient.

To ensure integrity, links are generated with a cryptographic signature. Do not attempt to construct your own links!

Use with OAuth​

If you're launching the user into an OAuth flow, you won't be sending the user a direct link to HealthEx, but rather to your application. You will then launch them into an OAuth flow. When calling the Authorization Request (/oauth/authorize) API, you will need to include the the xid query parameter in this request instead.

In order to get a valid value for the xid parameter, you could parse the query parameter out of the getPatientLink API above, but there is also a similar API to get only a signed external ID. You need to make the following API call:

POST https://api.healthex.io/v1/projects/694d61c2-3f1b-4dc8/signed-external-id
Accept: application/json
Authorization: Bearer <your JWT token>
{
    "externalId": "123-456-0000"
}

The only difference is this API will return only the signed external ID, rather than a full link. You can use this value as the xid parameter in the OAuth flow.

See Also​