Skip to main content

Add Patients by Unique Link

HealthEx's unique patient link functionality allows you to associate an external ID (patient reference ID) with a patient without needing to manually add them to a project beforehand.

This allows you to use your organization's internal identifiers (such as an MRN or member ID) to refer to a patient, ensuring you can unambiguously identify them when they complete the consent flow.

From the patient's perspective, the experience is identical to a standard patient link—the association with your supplied external ID happens transparently in the background.

Prerequisites​

Before generating a unique link, make sure you have:

  • 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 (e.g., MRN or member ID) you want to encode in the link.

Identifying Your Project ID​

To generate a unique link for a project, locate your project's unique identifier:

  1. Log in to HealthEx and navigate to Home.
  2. Select your project from the projects list to view its details.
  3. Copy the project ID from the browser URL:
    https://app.healthex.io/#/projects/{project-id}/patient-management

Example Request​

For the examples below, we will use the following values:

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

Make a POST request to the /link endpoint:

POST https://api.healthex.io/v1/projects/694d61c2-3f1b-4dc8/link
Content-Type: application/json
Accept: application/json
Authorization: Bearer <your JWT token>

{
  "externalId": "123-456-0000"
}

A successful response returns a string containing the complete unique URL:

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

You can now send this link directly to your patient.

Do Not Construct Links Manually

To ensure security and data integrity, links are generated with a cryptographic signature. Do not attempt to manually format or construct your own unique links!

If you want patients redirected back to your application after completing (or declining) the consent flow, you can configure a hosted redirect. To set this up, allowlist your redirect URL in project settings and pass a redirectUri query parameter on the link.

See Redirecting Patients After Consent for complete details.

(Note: If you are integrating using OAuth instead, see Use with OAuth below.)

Use with OAuth​

If you launch users via an OAuth flow, patients will initiate the process from your application rather than following a direct HealthEx link.

In this flow, pass the signed external ID using the xid query parameter when calling the Authorization Request endpoint (/oauth/authorize).

To get a signed external ID string without generating a full URL, use the /signed-external-id endpoint:

POST https://api.healthex.io/v1/projects/694d61c2-3f1b-4dc8/signed-external-id
Content-Type: application/json
Accept: application/json
Authorization: Bearer <your JWT token>

{
  "externalId": "123-456-0000"
}

This endpoint returns only the signed token string, which you can pass directly as the xid parameter in your OAuth authorization request.

See Also​