Patient Events Notification APIs
Beta
This API is in a stage of development that may be subject to change or deprecation and may not yet be feature complete or perform consistently.
General
As a builder, you can subscribe to real-time updates on your patients' clinical events from networks that support such functionality. This allows for a constantly up-to-date, refreshed picture of the patient's clinical information.
You can consume notification-based data by querying the Zus Operational Data Store (ODS) as you normally would, or optionally work with a Zus representative to subscribe to to updates.
Event Types
Medication Events
When you subscribe patients to the Zus Medication Events service, new prescription activity will automatically be updated within Zus ODS.
For each fill, Zus will create a MedicationRequest and MedicationDispense resource. With each fill, specific labels on the new MedicationDispense resource will alert you to the following scenarios:
- The prescription picked up is a new medication, denoted by a PMANewRx label.
- The prescription picked up is a refill, denoted by a PMARefill label.
- The prescription picked up is from a new prescriber, denoted by a PMANewPrescriber label.
- The prescription picked up is a controlled substance, denoted by a PMAControlledSubstance label.
- The prescription picked up has no refills remaining, denoted by a PMANoRefillsRemaining label.
Additionally, if the patient was due to refill a prescription, but the refill did not occur, the last confirmed MedicationDispense resource will have a specific label indicating:
- The prescription has a refill that is overdue (5 days past the expected refill date), denoted by a PMARefillNotPickedUp label on the most recent MedicationDispense.
The following example MedicationDispense resource illustrates the way that these labels will appear as extension values from the SureScripts patient notification system. In this case, these labels illustrate that the medication filled was a refill and there are no refills remaining. (Note, FHIR resource is truncated to focus on the labels).
{
"resourceType": "MedicationDispense",
"id": "fa6eadd7-baa5-4c86-9527-8acd8d7c5add",
"extension": [
{
"url": "http://surescripts.net/fhir/CodeSystem/notification-generated-time",
"valueInstant": "2022-09-19T10:46:02+00:00"
},
{
"id": "9bbd7253-350c-458a-856e-f8827e9d4c26",
"url": "http://surescripts.net/fhir/CodeSystem/patient-notification-types",
"valueString": "PMARefill"
},
{
"id": "60d1c445-e4e2-4fcd-9361-3e4150d4a80c",
"url": "http://surescripts.net/fhir/CodeSystem/patient-notification-types",
"valueString": "PMANoRefillsRemaining"
}
}
ADT Events
When you subscribe patients to the Zus ADT Events service, a patient's aggregate profile is updated automatically any time they are admitted to a hospital, transferred to another facility, or discharged.
For each event, Zus will create or update an Encounter resource, along with corresponding resources for any diagnoses, practitioners, or facilities relevant to the event.
When sample patient John is admitted to Community Medical Center with nausea, the following Encounter resource is created in Zus:
{
"resourceType": "Encounter",
"id": "cf53e4ef-611c-48d5-9a22-1031790e583a",
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "VN",
"display": "visit number"
}
],
"text": "visit number"
},
"value": "123456789"
}
],
"class": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "I",
"display": "Inpatient"
},
"serviceType": {
"coding": [
{
"code": "285",
"display": "General Medicine"
}
],
"text": "General Medicine"
},
"participant": [
{
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "ATND",
"display": "attender"
}
]
}
],
"individual": {
"reference": "Practitioner/85fe2ec9-be0a-4329-ad13-6acfe0e27849",
"type": "Practitioner"
}
}
],
"period": {
"start": "2022-11-11T15:45:00.000Z"
},
"diagnosis": [
{
"condition": {
"reference": "Condition/7616e37e-e284-4287-b32f-03dbd0f07926",
"type": "Condition"
},
"use": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/diagnosis-role",
"code": "AD"
}
]
}
}
],
"location": [
{
"location": {
"reference": "Location/2fb8fb58-93b6-4429-99e9-4cfaa370c22c",
"type": "Location"
}
},
{
"location": {
"display": "Community Medical Center"
}
}
]
}
When he is later discharged with a diagnosis of Celiac Disease, the Encounter resource is update to include a stop time and discharge diagnosis:
{
"resourceType": "Encounter",
"id": "cf53e4ef-611c-48d5-9a22-1031790e583a",
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "VN",
"display": "visit number"
}
],
"text": "visit number"
},
"value": "123456789"
}
],
"class": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "I",
"display": "Inpatient"
},
"serviceType": {
"coding": [
{
"code": "285",
"display": "General Medicine"
}
],
"text": "General Medicine"
},
"participant": [
{
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "ATND",
"display": "attender"
}
]
}
],
"individual": {
"reference": "Practitioner/85fe2ec9-be0a-4329-ad13-6acfe0e27849",
"type": "Practitioner"
}
}
],
"period": {
"start": "2022-11-11T15:45:00.000Z",
"end": "2022-11-11T18:10:00.000Z"
},
"diagnosis": [
{
"condition": {
"reference": "Condition/7616e37e-e284-4287-b32f-03dbd0f07926",
"type": "Condition"
},
"use": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/diagnosis-role",
"code": "AD"
}
]
}
},
{
"condition": {
"reference": "Condition/287c9d74-a7d3-9s82-90b6-h8732k73b07f",
"type": "Condition"
},
"use": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/diagnosis-role",
"code": "DD"
}
]
}
}
],
"location": [
{
"location": {
"reference": "Location/2fb8fb58-93b6-4429-99e9-4cfaa370c22c",
"type": "Location"
}
},
{
"location": {
"display": "Community Medical Center"
}
}
]
}
Lab Events
When sample patient John undergoes a lipid panel test, new resources are added to his patient profile in Zus as soon as the results come in. We'd expect to see the following diagnostic report, with references to each test result as an Observation resource:
{
"resourceType": "DiagnosticReport",
"id": "6c03ccbb-9ce2-4c36-9172-68067047a4fbVERSION1",
"code": {
"coding": [
{
"code": "2600000334",
"display": "CHOLESTEROL, TOTAL"
},
{
"system": "http://www.ama-assn.org/go/cpt",
"code": "80061"
}
]
},
"subject": {
"reference": "Patient/28b2fb19-7625-47f4-9fe2-6075eb0262a3",
"type": "Patient"
},
"effectiveDateTime": "2022-11-11",
"issued": "2022-11-23T05:36:00.000Z",
"performer": [
{
"reference": "Practitioner/b0386767-c02b-4512-919f-9fff9843e599",
"type": "Practitioner"
}
],
"result": [
{
"reference": "Observation/60ccfa37-aa1e-4b39-bfe7-2dbd91d16fdc",
"type": "Observation"
},
{
"reference": "Observation/fc6f58b6-b073-4036-98c8-e8914e26321e",
"type": "Observation"
},
{
"reference": "Observation/75cf31ae-d245-4660-8cf4-87e0d376302e",
"type": "Observation"
}
]
}
Data types
Medication events generate the same clinical resource types as pull-based medication history requests to Surescripts.
Clinical
The main clinical resources generated today are:
Medication Events
ADT Events
Lab Events
Administrative
Several foundational administrative resources are referenced to support the clinical resource:
Auditing and analysis
We also include the raw documents for builders that prefer to process them on their own. These are stored in the following resources:
Change Notifications
Patient data events are captured as new or updated resources in the Zus ODS. To be proactively notified of these events, you must subscribe to changes in the relevant resources. Setting up a change notification currently requires direct Zus support. Please contact the Zus team.
Enrollment and required demographics
The Zus team will be supporting initial pilots with the enrollment process. A customer-led process will be available soon. When enrolling your patients, we recommend including the fullest set of patient demographics you can collect for maximum success in receiving events for your patients, including:
-
*First Name
-
*Last Name
-
*DOB
-
*Gender
-
*Address Line 1
-
*City
-
*State
-
*Zip
-
Phone
-
Email
*Required
Updated 18 days ago