Enrolling & Refreshing

To obtain data from Zus data partners, customers can enroll patients in a Zus subscription, or alternatively trigger one-time queries of the networks.

Zus subscriptions

By enrolling patients in subscriptions, customers can ensure that the ZAP is kept up-to-date via a combination of Zus's intelligent refresh and notification-based partners.

Our subscriptions may include the following data types:

Data typeAvailability
EHR networksTraditionally EHR networks are query-based, however Zus intelligent refresh will use event-based triggers to proactively refresh the ZAP.
Pharmacy-sourced medication dataPharmacy data is primarily query-based, however Zus intelligent refresh use event-based triggers to proactively refresh the ZAP. We also refresh medication history on a regular basis to ensure it is up-to-date.
Admission notifications (ADT)By definition, admission notifications are proactive in nature and "pushed" to the ZAP.
Lab notificationsUpon enrollment in a subscription, the patient's 2-year lab history is pulled. Any new results are then "pushed" to the ZAP.

Intelligent refresh

Zus automatically initiates a refresh of data networks when our engine has reason to believe new data may be available. Today, the following triggers are supported:

  • Getting up to speed: Upon initial enrollment, patients will receive an initial history refresh in order to populate the ZAP.
  • Scheduled Appointments: Zus will refresh patient data before your appointments to empower comprehensive chart prep. When we detect an appointment with another care organization via third-party data networks, we'll automatically schedule a follow-up refresh to capture visit documentation.
  • ADT alerts Zus will refresh ZAP data upon receipt of an ADT message and follow up regularly throughout a patient's stay
  • Medication fills ZAP data will be refreshed any time the patient starts a new medication, and after the expected refill date for existing medications.

More triggers are being built out!

Enrolling via API

The zap-data-subscriptions API, available in the Zus Postman collection, can be used to manage enrollment for your patient population.

Available actions include:

Enrolling via Integration

Zus can automatically enroll patients into packages for clients who are leveraging integrations with our EHR partners. Read more about those automated enrollments here.

One-time queries

Customers may also initiate one-time queries of the networks for patients that are not enrolled in a subscription. This is done using the Patient History API or in the ZAP UI.

Create a new job

To initiate a one-time query, create a new job using the Patient History API. Ensure the patient(s) being queried have the necessary demographics and that you have an active treatment relationship prior to initiating.

Each job must include an attestation of consent and the request practitioner's information. Optionally, you may "schedule" the job by specifying a target date for job completion. Zus will initiate the job approximately 36 hours prior to the target date. If you create a job within 36 hours of its target date, Zus will initiate it right away.

POST http://api.sandbox.zusapi.com/patient-history/jobs

{
    "data": {
        "type": "patient-history/jobs",
        "attributes": {
            "requestConsent": true,
            "practitioner": {
                "npi": "1013085661",
                "name": "Testfirstname Testlastname",
                "role": "309343006"
            },
        },
        "targetDate": "2023-09-01T07:00:00Z",
        "relationships": {
            "patient": {
                "data": {
                    "type": "fhir/Patient",
                    "id": "{{ZusPatientID}}"
                }
            }
        }
    }
}

Check job status

To check the status of a patient history job,

GET http://api.sandbox.zusapi.com/patient-history/jobs/{{jobID}}

The response includes a status for the overall job, as well as a status for each of the underlying connectors that the job initiated.

Jobs and connectors can have the following statuses:

Status NameStatus Description
InitializeThe job or connector has been queued but has not yet kicked off
In progressA connector is still in progress
DoneThe job or connector has successfully finished processing. All connectors need to reach a status of done for the umbrella job status to be done
ErrorThe job or connector experienced a system error. The umbrella patient history job will always show an error status if at least one of the underlying connectors shows an error status

A single patient history job may interact with multiple documents and FHIR resources across multiple responding organizations. Any one of these interactions may fail due to network connectivity, system reliability, or data integrity. To keep patient history status messaging informative without being noisy, Zus adheres to the following standards:

  • The following scenarios are considered fatal and will always cause a connector to report an error:
    • Zus experienced a system error that caused one or more of the connectors to become unavailable
    • Zus was entirely unable to connect to the data source
    • Zus experienced a system error and failed to transform or load data from one or more documents; we will report an error status even if other documents were processed successfully
    • A data source found the demographics of a patient invalid and rejected the request
  • The following scenarios are NOT considered fatal and will not be reported as errors today
    • A data source failed to find data on a patient
    • A responding organization indicated that data was available on a patient, but responded with 404s when Zus tried to retrieve the document (relevant for CommonWell and Carequality)
    • FHIR resources transformed from the source data failed validation (e.g., if required fields are missing or codes are invalid) and did not get written to ODS

We recommend NOT retrying when you see an error reported on a patient history job through the /jobs endpoint. We are working to make error states vanishingly rare; when they do occur, retries are unlikely to deliver a different outcome. Instead, please reach out to your support contacts if you see a spike in jobs that experienced an error.