Getting Consent Record Details
You can get details about a single consent record using HealthEx APIs. A consent record represents consent given by a unique combination of patient, study, and consent type. Consent records provide additional context about the patient's consent beyond a simple "yes" or "no".
To learn more about why you might want to fetch these details, see About Consent Auditing.
Identifying a Consent Record
You will generally identify a consent record from the response of another API call, such as getPatientConsents. The responses to these APIs contain a consentRecordId (or consentRecordIds) field that refers to the underlying record(s) driving the response.
For example, take the following response snippet:
[
{
"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 Request
For this example, we will retrieve the details for Consent Record ID 21.
Make a GET request to the /consents/{id} endpoint:
GET https://api.healthex.io/v1/consents/21
Accept: application/json
Authorization: Bearer <your JWT token>
(Note: This API requires a valid JWT token. See the Authentication guide for setup instructions.)
Response Payload
The response body returns a detailed consent object:
{
"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"
}
Key Fields
While the payload contains many standard identifiers, here are a few critical fields used for auditing:
| Field | Description |
|---|---|
timestamp | Captures the exact moment the patient consented. |
studySnapshotId | A unique ID referencing the exact content of the study at the time of consent. If two records share a studyId but have different snapshot IDs, the study was modified between the two consents (meaning patients may have viewed different information). |
consentUIFlow | Captures the specific UI flow the patient went through (i.e., the set of screens they were shown). |
uiHash | A unique ID referencing the specific HealthEx user interface application version used. Differing hash values indicate patients may have had slightly different UI experiences. |
To see exactly what the user saw during this flow, see Getting Consent Screenshots.
Getting All Consent Records for a Patient
You can also retrieve all consent records for a specific patient within your organization. This is useful when you need to audit a patient's complete consent history across all studies and consent types.
Identifying a Patient
You can look up a patient using one of four identifier query parameters. Only provide one identifier per request.
| Parameter | Description |
|---|---|
email | Patient's email address |
phone | Patient's phone number |
patientId | HealthEx's internal patient reference ID |
externalId | Your system's external identifier for the patient |
Making the API Call
To retrieve all consent records for a specific patient ID:
GET https://api.healthex.io/v1/patients/consents?patientId=17d4513f-73e8
Accept: application/json
Authorization: Bearer <your JWT token>
Alternatively, querying by email would look like this:
GET https://api.healthex.io/v1/patients/consents?email=patient@example.com
Accept: application/json
Authorization: Bearer <your JWT token>
Optional Parameters
The API supports several optional parameters for pagination and filtering:
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 (accepts RFC 2822 or ISO 8601 formats).
Example Request with Pagination & Date Filtering:
GET https://api.healthex.io/v1/patients/consents?patientId=17d4513f-73e8&limit=50&offset=0
Accept: application/json
Authorization: Bearer <your JWT token>
If-Modified-Since: Fri, 09 Feb 2024 01:10:13 GMT
Response Format
The response returns a paginated list of consent records alongside their associated base64-encoded 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"
}
]
}
]
}
Response Details:
total: The total number of consent records available for this patient.results: An array containing both theconsentRecord(identical in format to the single-record API) and an array ofscreenshots.pdfUrl(deprecated): A URL to a PDF of the consent record. Proof-of-consent PDFs are being phased out. This field is still populated today but new integrations should not depend on it.
This comprehensive view allows you to see the complete consent audit trail for a patient, including the visual evidence of exactly what they agreed to.