Skip to main content

Finding All Patients Who Didn't Consent

In most circumstances, you will only be interested in which patients consented to a project. For example, if you are making an API call to check whether or not it is appropriate to release a patient's medical data to a project, you might query for all the patient IDs that have consented to that project. The absence of a patient ID in that list can safely be assumed to implicitly mean the patient has not consented.

However, in some limited circumstances, you might want to explicitly list out all the patients who didn't consent to a project. For example, as a health system, you might want to generate a list of these patients so you can send them an email urging them to consider enrolling.

The good news is that this use case is also supported by the getPatientConsents API!

Getting Started​

To get started, first follow the steps in Finding All Consented Patients For a Project. We will simply be modifying this API call slightly. We will also use the same example values for simplicity.

Adjusting the API Call​

Authentication Required

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

To instead find all the patients who didn't consent, you need to alter your API request body by adding a single field, hasConsented, with a value of [false]. This will make your request look like:

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-4dc8",
    "hasConsented": [false]
}

Response Payload​

This will give you a very similar response, except that the patients listed will now be the ones who did not consent:

[
    {
        "healthcareOrganizationId": "56696fdb-2e0d",
        "patientId": "9baf4974-ac0f",
        "consents": [
            {
                "consentType": "PATIENT_DIRECTED_DATA_EXCHANGE",
                "studyId": "694d61c2-3f1b-4dc8",
                "hasPatientConsented": false,
                "source": "STUDY",
                "consentRecordId": "21",
                "expirationTimestamp": "2024-04-21T19:05:59.516Z"
            }
        ]
    }
]

To confirm you did this correctly, you can check that hasPatientConsented is set to false in all objects in the response.

If you need to get all the patients who consented and all the patients who did not consent, you can actually do this in a single API call.

You just need to adjust the hasConsented array to include both boolean values:

"hasConsented": [true, false]

In this case, the response will include all patients, and you can look at the hasPatientConsented field to determine whether each specific patient consented or not.

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

See Also​