Skip to main content

Finding All Consented Patients For a Project

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

Identifying Your Project ID​

  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 will 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:

  • 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 find the patients who have consented to enroll in this project, 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-4dc8"
}

Response Payload​

The response body returns an array with an entry for every patient who matched your query:

[
    {
        "healthcareOrganizationId": "56696fdb-2e0d",
        "patientId": "17d4513f-73e8",
        "consents": [
            {
                "consentType": "PATIENT_DIRECTED_DATA_EXCHANGE",
                "studyId": "694d61c2-3f1b-4dc8",
                "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-4dc8",
                "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 project, 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 project 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 project 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​