Skip to main content

Finding All Consented Patients For a Study

In some cases, you may want to know all the patients who have consented to a specific study added by your organization. This can be accomplished with using the getPatientConsents API.

Identifying a Study​

First, 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 it in the HealthEx Application.
  2. Navigate to to the details page for the study in question.
  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 types you are interested in. The getPatientConsents API allows you to query multiple consent types at once, if needed. See Key Concepts for a full explanation of consent types

Example Values​

For this example, we will use the following values:

  • 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 find the patients who have consented to enroll in this study, you would make the following API call:

POST https://api.healthex.io/v1/consents
Content-Type: application/json
Accept: application/json
Authorization: Bearer <your JWT token>
{
    "consentTypes": ["PATIENT_DIRECTED_DATA_EXCHANGE"],
    "studyId": "694d61c2-3f1b"
}

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:

[
    {
        "healthcareOrganizationId": "56696fdb-2e0d",
        "patientId": "17d4513f-73e8",
        "consents": [
            {
                "consentType": "PATIENT_DIRECTED_DATA_EXCHANGE",
                "studyId": "694d61c2-3f1b",
                "hasPatientConsented": true,
                "source": "STUDY",
                "consentRecordId": "21",
                "expirationTimestamp": "2024-04-21T19:05:59.516Z"
            }
        ]
    },
    {
        "healthcareOrganizationId": "56696fdb-2e0d",
        "patientId": "ef37fadb-6b28",
        "consents": [
            {
                "consentType": "PATIENT_DIRECTED_DATA_EXCHANGE",
                "studyId": "694d61c2-3f1b",
                "hasPatientConsented": true,
                "source": "STUDY",
                "consentRecordId": "77  ",
                "expirationTimestamp": "2024-04-21T19:05:59.516Z"
            }
        ]
    }
]

As shown, the response will consist of a top-level array with an entry for every patient who matched your query. Given your goal was to simply find out which patients consented, this can be accomplished by simply collecting the patientId field from each object in the top-level array.

For the example above, that means that 2 total patients consented to this study, with ids 17d4513f-73e8 and ef37fadb-6b28

For this use case, you can generally ignore the consents array - it will always only have one entry since you queried for a single study and a single consent type. More complicated use cases might look at that single entry to find out more information; for example the source property will tell you which patients gave direct study consent as opposed to broad consent.

The getPatientConsents API is extremely powerful and can handle many additional use cases. To learn more, check out the API reference.

See Also​