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.

The above API is designed for organizations to check consent on behalf of patients. HealthEx also provides an API for patients to check their own consent status directly.

Authentication​

Unlike the organization API above, this endpoint requires patient authentication. The request must include a valid patient token or patient read-only token, which is obtained through the HealthEx patient authentication flow.

Making the API Call​

To check a patient's consent status for a specific project:

GET https://api.healthex.io/v1/patient/19cff418-7d80/consent/status?projectId=694d61c2-3f1b
Accept: application/json
Authorization: Bearer <patient JWT token>

To check IAS (Individual Access Services) consent status, omit the projectId parameter:

GET https://api.healthex.io/v1/patient/19cff418-7d80/consent/status
Accept: application/json
Authorization: Bearer <patient JWT token>

Response Format​

{
    "hasPatientConsented": true,
    "expiresAt": "2027-04-04T06:59:59.000Z",
    "consentRecordId": "abc123-def456",
    "projectId": "694d61c2-3f1b"
}

Response Fields​

  • hasPatientConsented - A boolean indicating whether the patient has an active consent
  • expiresAt - The ISO 8601 timestamp when the consent expires, or null if no consent record exists
  • consentRecordId - The unique identifier of the consent record, if one exists
  • projectId - The project ID if checking project consent, null for IAS consent

Authorization Requirements​

  • User Type: PATIENT or PATIENT_READ_ONLY
  • Ownership: The authenticated patient must match the patientId in the request path

Error Responses​

Bad Request​

HTTP 400 - The request contains invalid parameters. This may occur when an invalid projectId is provided.

Unauthorized​

HTTP 401 - The token is missing, invalid, or expired.

Forbidden​

HTTP 403 - The token does not have permission to access this patient's data. This typically happens when the token belongs to a different patient.

All Done!​

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

See Also​