Skip to main content

Getting Consent Record Details

You can get details about a single consent record using HealthEx APIs. A consent record represent consent given by a unique combination of patient, study, and consent type. Consent records provide additional information about the patient's consent beyond just whether they consented or not.

For more information on why you might want this, see About Consent Auditing.

You will generally identify a consent record from another API call, such as getPatientConsents. The responses to these APIs will contain a consentRecordId or consentRecordIds field that refers to the consent record(s) that the response was derived from. For example, take the following response:

[
    {
        "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"
            }
        ]
    }
]

In this case, we have received the IDs of two consent records, 21 and 77.

Example Values​

For this example, we will use the following values:

  • Consent Record ID: 21

Making the API Call​

To get details about the consent record, you would make the following API call:

GET https://api.healthex.io/v1/consents/21
Accept: application/json
Authorization: Bearer <your JWT token>

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",
    "id": "21",
    "timestamp": "2024-02-09T01:10:13.000Z",
    "patientId": "17d4513f-73e8",
    "studyId": "694d61c2-3f1b",
    "consentType": "DATA_AUTHORIZATION",
    "consentStatus": "OPTED_IN",
    "expirationTimestamp": "2026-05-05T06:59:59.000Z",
    "consentStats": {
        "sessionLength": 0,
        "interactions": []
    },
    "studySnapshotId": "0a7f8266-60ae",
    "consentConfigSnapshotId": null,
    "consentUIFlow": "PER_STUDY_PRESCREEN",
    "uiHash": "3deda814a6f9d08e106d"
}

There's a lot of information here! Here's a few of the most important fields:

  • timestamp captures exactly when the patient consented
  • studySnapshotId captures a unique ID referencing the content of the study. If two records have the same studyId but different studySnapshotId, then the study was modified between the two consents (and thus the patients may have seen different info during the consent process)
  • consentUIFlow captures what "UI flow" the patient went through, i.e. what set of screens they saw.
  • uiHash captures a unique ID referencing the HealthEx user interface application version. If two records have differing uiHash values, the two patients may have had slightly different experiences during their consent process.

These fields may inspire the follow up question, "what exactly did the user see?" To answer this question, see Getting Consent Screenshots.

You can also retrieve all consent records for a specific patient within your organization. This is useful when you need to audit the complete consent history for a patient across all studies and consent types.

Identifying a Patient​

You can identify a patient using one of four identifier types:

  • email - Patient's email address
  • phone - Patient's phone number
  • patientId - HealthEx patient reference ID
  • externalId - Patient external identifier from your system

Only one identifier should be provided per request.

Making the API Call​

To get all consent records for a patient, you would make the following API call:

GET https://api.healthex.io/v1/patients/consents?patientId=17d4513f-73e8
Accept: application/json
Authorization: Bearer <your JWT token>

You can also use other patient identifiers:

GET https://api.healthex.io/v1/patients/consents?email=patient@example.com

Optional Parameters​

The API supports several optional parameters:

  • limit - Maximum number of results to return (default: 100, max: 1000)
  • offset - Number of results to skip for pagination (default: 0)
  • If-Modified-Since header - Only return records modified after this date (RFC 2822 or ISO 8601 format)

Example with pagination and date filtering:

GET https://api.healthex.io/v1/patients/consents?patientId=17d4513f-73e8&limit=50&offset=0
If-Modified-Since: Fri, 09 Feb 2024 01:10:13 GMT

Response Format​

The response will include both the consent records and their associated screenshots:

{
    "total": 3,
    "results": [
        {
            "consentRecord": {
                "healthcareOrganizationId": "56696fdb-2e0d",
                "id": "21",
                "timestamp": "2024-02-09T01:10:13.000Z",
                "patientId": "17d4513f-73e8",
                "studyId": "694d61c2-3f1b",
                "consentType": "DATA_AUTHORIZATION",
                "consentStatus": "OPTED_IN",
                "expirationTimestamp": "2026-05-05T06:59:59.000Z",
                "consentStats": {
                    "sessionLength": 0,
                    "interactions": []
                },
                "studySnapshotId": "0a7f8266-60ae",
                "consentConfigSnapshotId": null,
                "consentUIFlow": "PER_STUDY_PRESCREEN",
                "uiHash": "3deda814a6f9d08e106d"
            },
            "screenshots": [
                {
                    "id": "screenshot-1",
                    "data": "base64-encoded-image-data",
                    "contentType": "image/png"
                }
            ]
        }
    ]
}

The response includes:

  • total - Total number of consent records available for the patient
  • results - Array of consent records with their associated screenshots
  • Each result contains both the consentRecord (same format as the single record API) and an array of screenshots

This comprehensive view allows you to see the complete consent audit trail for a patient, including visual evidence of what they saw during each consent process.