Skip to main content

Finding All Studies a Patient Consented To

It can be useful to find all of the studies a single patient in your organization has consented to. This can be accomplished with using the getPatientConsents API.

Identifying a Patient​

You can identify the patients the same way you would for Basic Consent Checking.

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:

  • Patient ID: 19cff418-7d80
  • 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"],
    "patientId": "19cff418-7d80"
}

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": "`19cff418-7d80",
        "consents": [
            {
                "consentType": "PATIENT_DIRECTED_DATA_EXCHANGE",
                "studyId": "694d61c2-3f1b",
                "hasPatientConsented": true,
                "source": "STUDY",
                "consentRecordId": "21",
                "expirationTimestamp": "2024-04-21T19:05:59.516Z"
            },
            {
                "consentType": "PATIENT_DIRECTED_DATA_EXCHANGE",
                "studyId": "2807a377-a9b7",
                "hasPatientConsented": true,
                "source": "STUDY",
                "consentRecordId": "77",
                "expirationTimestamp": "2025-03-23T10:05:33.382Z"
            }
        ]
    },
]

As shown, the response will consist of a top-level array with a single entry for the patient that you queried for. That single entry will have a consents property, which is an array. This is where the information you're looking for will be. There will be one entry in the array for every study that the patient has consented to. In the simplest case, you will just want to collect the studyId for every entry in this array.

For the example above, that means that this patient consented to 2 total studies:

  • Study id 694d61c2-3f1b
  • Study id 2807a377-a9b7

For most cases, you can generally ignore the other properties other than studyId. More complicated use cases might look at them 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​