One-Time Queries

Customers may 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

JSON

{
    "data": {
        "type": "patient-history/jobs",
        "attributes": {
            "requestConsent": true,
            "practitioner": {
                "npi": "1013085661",
                "name": "Testfirstname Testlastname",
                "role": "309343006"
            },
            "priority": false,
            "chartBuildType": "pro-ehr-only" //optional, more information below
        },
        "targetDate": "2023-09-01T07:00:00Z",
        "relationships": {
            "patient": {
                "data": {
                    "type": "fhir/Patient",
                    "id": "{{ZusPatientID}}"
                }
            }
        }
    }
}

Chart build types

The chartBuildType attribute allows you to specify which type of patient history job you want to run. This attribute is optional and only available to builders who have an order form with multiple chart build types. If you do not supply it, Zus will use the default chart build type configured for your account during implementation.

Zus currently supports the following chart build types:

Queued job behavior

Jobs that have an attribute of "priority": true execute immediately upon submission. Jobs that don't supply a priority attribute, or that set "priority": false, get added to our limiter queue, which manages bulk volume to prevent us from overwhelming responders on CommonWell and Carequality.

The queue prioritizes jobs on a FIFO basis and smooths the rate at which they are submitted to the network to avoid large bursts of requests. Depending on how large the queue is when you submit a job, it may take up to 36 hours to run.

Jobs that have an attribute of "priority": true are throttled at a rate of 10 jobs per minute.

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:

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.