Skip to main content

Basic Consent Checking

The simplest thing you can do with the HealthEx APIs is check a single consent. What does that mean? It means checking whether one specific patient has given one specific type of consent to one specific study. If you need to check more than one of any of these values, there are other APIs that permit this and will be discussed later in the documentation. But let's start simple!

To make an API call to check a single consent, we'll need:

  • The reference ID, external ID, email, phone number of the patient
  • The ID of a study added by your organization
  • The consent type to check

Identifying a Patient​

The first thing you'll need to do is identify the patient you're interested in.

Identifying a Patient From the HealthEx Study Manager​

You may want to check the consent status of one of the patients you've already identified as a candidate for one of your studies. In the HealthEx application, you can find a patient ID by navigating to the HealthEx Study Manager for one of your studies. The patient ID is listed under the "Reference ID" column.

Identifying a Patient Using an External ID​

If you added the patient to HealthEx using our Add Patient API, you had the opportunity to associate the patient with an "external ID", which is basically an arbitrary identifier of your choice. This would likely be your own organization's identifier for this patient, which might be a medical record number (MRN), member identifier, or any other Master Patient Index (MPI) identifier.

You can read more about adding an external ID in Adding Patients to Projects

Identifying a Patient Using Contact Information​

You can also simply identify a patient using a piece of their contact information, i.e. their email or phone number. This is often the simplest way to identify a patient, but keep in mind that patients may have multiple emails or phone numbers. If possible, using the HealthEx reference ID or external ID is more reliable.

Identifying a Study​

Next, you'll need to identify a study you're interested in. You'll need the study's ID.

To find a study's ID:

  1. Locate the study in the HealthEx web application. A list of studies can be found on the in the "Research" section. You can use the search functionality to find your study if needed.
  2. Navigate to the "Details" page for the study in question by clicking on the study in the list from Step 1 and (if necessary) selecting the "Details" tab.
  3. You can then find the study ID in the URL the page. For example, if the URL is https://app.healthex.io/#/research-studies/694d61c2-3f1b-4dc8-aa1c-2012fc735e57/details, then 694d61c2-3f1b-4dc8-aa1c-2012fc735e57 is the study ID.

You'll also need to select the consent type you are interested in. See Key Concepts for an explanation of consent types.

Example Values​

For this example, we will use the following values:

  • Patient ID: 19cff418-7d80
  • Study ID: 694d61c2-3f1b
  • Consent Type: PATIENT_DIRECTED_DATA_EXCHANGE (has the patient consented to accessing their data on a public network)

Making the API Call​

To check whether this patient has consented to enroll in this study, you would make the following API call:

GET https://api.healthex.io/v1/patients/consented/study/694d61c2-3f1b-4dc8/PATIENT_DIRECTED_DATA_EXCHANGE?patientId=19cff418-7d80 \
Accept: application/json
Authorization: Bearer <your JWT token>

If you're using a different kind of patient identifier, you'll need a different query parameter. patientId, externalId, email, and phone are all supported.

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

The response body will look something like this:

{
    "consentType": "PATIENT_DIRECTED_DATA_EXCHANGE",
    "studyId": "694d61c2-3f1b",
    "hasPatientConsented": true,
    "source": "STUDY",
    "consentRecordId": "12",
    "expirationTimestamp": "2026-04-04T06:59:59.000Z",
    "consentDataScopes": []
}

All you need to do for this simple use case is to check the boolean value of hasPatientConsented.

For more details, see the hasPatientConsentedToStudy API reference.

All Done!​

That's it! You've made your first API call to check patient consent with HealthEx!

See Also​