Patient History API

🚧

Beta

Please note that this page refers to an API in a stage of development that may be subject to change.

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.

The API will automatically pull the organizational and provider information from your authenticated user, but if there is no linked practitioner or if you need to override those values, you can use the relevant parameters to do so.

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:

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:

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
  • City
  • State
  • Zip
  • At minimum one of the following (ideally all to maximize your patient match rate in Zus's data ecosystem)
    • Address Line 1
    • Phone
    • Email