Skip to main content

Basic Consent Checking

The simplest thing you can do with the HealthEx APIs is check a single consent. This means checking whether one specific patient has given one specific type of consent to one specific study.

(If you need to check multiple patients, studies, or consent types at once, there are bulk APIs that permit this, which are discussed later in the documentation. But let's start simple!)

To check a single consent, you need:

  • A patient identifier (reference ID, external ID, email, or phone number).
  • The ID of a project/study managed by your organization.
  • The consent type to check.

Identifying a Patient​

First, you need to identify the patient you are querying. You can do this in three ways:

1. From the HealthEx Study Manager​

If you have already identified a patient as a candidate for a study, you can find their HealthEx Patient ID by navigating to the HealthEx Study Manager. The ID is listed under the Reference ID column.

2. Using an External ID​

If you added the patient to HealthEx using our Add Patient API, you had the opportunity to assign an External ID. This is your organization's internal identifier, such as a Medical Record Number (MRN) or Master Patient Index (MPI) identifier. Using this ID is highly reliable. (See Adding Patients to Projects for details.)

3. Using Contact Information​

You can identify a patient using their email or phone number. While this is often the simplest method, keep in mind that patients may have multiple emails or phone numbers on file. Using the HealthEx reference ID or your external ID is generally more reliable.

Identifying Your Project ID​

To find the ID of the study/project you are checking against:

  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

You also need to select the specific consent type you are verifying. See Key Concepts for a full explanation of available consent types.

Example Values​

For this example, we will use the following values:

  • Patient ID: 19cff418-7d80
  • Project ID: 694d61c2-3f1b-4dc8
  • Consent Type: PATIENT_DIRECTED_DATA_EXCHANGE

Making the API Call​

Authentication Required

This API requires a valid JWT token. See the Authentication guide for setup instructions.

To check whether this patient has consented to enroll in this project, 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 are using a different patient identifier, simply swap the query parameter. patientId, externalId, email, and phone are all supported.

Response Payload​

The response body returns the consent status and associated metadata:

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

For this simple use case, you only need to check the boolean value of hasPatientConsented.

For complete payload details, see the hasPatientConsentedToStudy API reference.

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

Patient Authentication Required

Unlike the standard API above, this endpoint requires a patient token:

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

Making the API Call​

To check a patient's consent status for a specific project, include the projectId parameter:

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

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

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

Response Payload​

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

Response Fields​

FieldDescription
hasPatientConsentedA boolean indicating whether the patient has an active consent
expiresAtThe ISO 8601 timestamp when the consent expires, or null if no consent record exists
consentRecordIdThe unique identifier of the consent record, if one exists
projectIdThe project ID if checking project consent, null for IAS consent

Error Responses​

Response CodeReason
400 Bad RequestThe request contains invalid parameters. This may occur when an invalid projectId is provided.
401 UnauthorizedThe token is missing, invalid, or expired.
403 ForbiddenThe 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​