Chart Builds

A Chart Build is a one-time retrieval of available patient history into the Zus Aggregated Profile (ZAP). Use it for a discrete clinical need, such as gathering history for a new-patient intake or a one-time chart review.

Chart Builds are the workflow previously described as “One-Time Queries.” You can request a build through the Patient History API or the Zus app. The underlying API remains the Patient History API.

Chart Builds and Monitoring

For patients you care for over time, enroll them in Monitoring so Intelligent Refresh can keep their ZAP current as care happens and before appointments.

A Chart Build retrieves history for a point in time. It does not enroll the patient in Monitoring or start ongoing Intelligent Refresh. Sources and historical lookback depend on the Chart Build type configured for your organization. Pharmacy history is included only when configured; Surescripts bulk history can take 24–36 hours to process, in addition to any queueing.

Chart Builds can also be requested alongside Monitoring when appropriate to your workflow and order form. A separately requested Chart Build is distinct from the automatic refreshes included with Monitoring and may incur an additional charge. Confirm the intended workflow with your Zus team.

Create a new job

To request a Chart Build, create a 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 requesting practitioner's information. Optionally, you may "schedule" the job by specifying a target date for job completion. For example, set targetDate to an ISO 8601 timestamp for the desired completion date. Zus initiates scheduled jobs approximately 36 hours before that date, or right away if submitted within that window. Job queueing and connector processing can affect completion; see the queue behavior below.

POST https://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"
        },
        "relationships": {
            "patient": {
                "data": {
                    "type": "fhir/Patient",
                    "id": "{{ZusPatientID}}"
                }
            }
        }
    }
}

Choose a Chart Build type

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. Please work with your Customer Success contact to determine what chartBuildType values are allowable for your organization.

The example uses pro-ehr-only. Use that value only if it is enabled for your organization; otherwise, use an allowed value or omit the optional attribute to use your configured default.

Queued job behavior

Jobs with "priority": true bypass the standard limiter queue and begin execution upon submission, subject to priority throttling. This does not mean every connector finishes immediately. 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 per builder and smooths the rate at which they are submitted to the network to avoid large bursts of requests. Depending on how large your particular queue already is when you submit a new job, it may take up to 72 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 https://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. A completed job does not guarantee that new data was found or that the patient’s history is complete.

The existing job status definitions are:

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

Do not automatically retry jobs that report an error through the /jobs endpoint; retries are unlikely to produce a different outcome. Contact Zus Support if you see a spike in job errors.

Related pages

• Patient Monitoring & Chart Builds
• Intelligent Refresh
• Network Requirements
• EHR Networks