🚧

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

The patient history API is a service that pulls the clinical and medication dispense history for a single patient from provider organizations and pharmacies across the US based on a Treatment Purpose of Use.

It takes the FHIR ID of a patient resource stored in the Zus FHIR store as a required parameter and optionally supports a date range as parameters to limit the length of history returned.

To use this API, your organization must have the patient's consent to retrieve and query their records (through a consent to treat or other process). You should indicate that this consent exists by using the consent parameter on this API call, or by adding an active FHIR Consent resource for the patient.

Specifications for this API are available here.

Data Types

The patient history API response includes the set of data needed for medication reconciliation and the transfer patients of between healthcare institutions. As a result, it contains a rich set of FHIR resources once Zus translates the underlying CDA and NCPDP documents.

Clinical

The main clinical resource generated today is:

• AllergyIntolerance
• CareTeam
• CarePlan
• Condition
• Consent (Advanced Directives)
• Coverage
• DiagnosticReport
• Encounter
• FamilyMemberHistory
• Immunization
• MedicalEquipment
• MedicationAdministration
• MedicationDispense
• MedicationRequest
• MedicationStatement
• Observation (Vitals and Labs)
• Patient
• Procedure

Administrative

Several foundational administrative resources are referenced to support the clinical resource:

• Location
• Medication
• Organization
• Practitioner
• RelatedPerson

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:

• Binary
• DocumentReference
• Provenance

Data Breadth

The underlying networks powering the Patient History API are not comprehensive (not all providers participate today), so the medical history for a given patient is only partial unless the patient has been seen only by network participants. Certain information may not be available or accurate in this report, including items that the patient asked not be disclosed due to patient privacy concerns, over-the-counter medications, low cost prescriptions, prescriptions paid for by the patient or nonparticipating sources, or errors in insurance claims information.

Additionally, given that the network is decentralized in nature, various participants may have downtime or be unavailable at any given time. At those times, the patient information they possess may not be available.

There may also be a potential for a false-positive match if the patient’s demographics sent in the message have information similar to another patient in the destination master patient index. Providers should verify the patient’s demographics and clinical history with the patient.

Demographics needed for patient matching

We recommend including the fullest set of patient demographics you can collect for maximum success, including:

• First Name
• Last Name
• DOB
• Gender
• Address Line 1
• City
• State
• Zip (5 digits or 5-4, separated by a hyphen)
• We also recommend including the following fields to maximize your patient match rate in Zus's data ecosystem
  • Phone
  • Email

Status Reporting

The /messages and /message-status endpoints on the patient history API allow users to check the status of a patient history job. These endpoints return 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:

• Initialize – the job or connector has been queued but has not yet kicked off
• In progress – a connector is still in progress
• Done – a connector or job has successfully finished processing; all connectors need to reach a status of done for the umbrella job status to be done
• Error – the job or connector experienced a system error; the umbrella patient history job will always show an error status if one of the underlying connectors shows an error status

Error states

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

To retry or not to retry?

We recommend NOT retrying when you see an error reported on a patient history job through the /messages or /message-status 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.