🚧

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.

On August 1, the following endpoints will be deprecated:

• Start a job - /patient-history/patient/{patient-id}/refresh
• Check the status of a job - /patient-history/message-status/{message-id}
• Get job messages - /patient-history/messages

For guidance on how to convert your existing requests to the new /patient-history/jobs API, please see the changelog announcement.

General

Providers require access to a patient's medical and medication history to make informed decisions about their care. With the Patient History API, developers can easily request the retrieval of this information, allowing providers to have a more complete picture of their patient's history and enabling them to provide personalized and effective treatment.

Data Types

The Patient History API retrieves data needed for medication reconciliation and the transfer of patients between healthcare institutions. Zus translates the underlying CDA and NCPDP documents into a rich set of FHIR resources. The resource types generated today are:

Auditing and Analysis

The underlying CDA and NCPDP documents are available through the following resource types:

• Binary
• DocumentReference
• Provenance

Data Breadth

The Patient History API's underlying networks are not comprehensive, meaning the history for a patient is partial unless they have exclusively been seen 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.

Getting started with the Patient History API

To submit a patient history job, you must provide a valid ID of a Patient resource that you wrote to the Zus FHIR Store.

Demographics needed for patient matching

It is required to provide a full set of patient demographics to maximize your chance of a successful patient match. This includes:

• First name
• Last name
• Birth date
• Gender
• Address line 1
• City
• State
• Zip (5 digits or 5-4, separated by a hyphen).

👍

To further maximize your patient match rate in Zus's data ecosystem, provide a patient's phone and email.

First, upsert a patient.

PUT https://api.sandbox.zusapi.com/fhir/Patient/?identifier=https://zusapi.com/test|test-identifier-value

{
    "resourceType": "Patient",
    "identifier": [
        {
            "system": "https://zusapi.com/test",
            "value": "test-identifier-value"
        }
    ],
    "name": [
        {
            "use": "official",
            "family": "Bergamel",
            "given": [
                "Soloman"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "1970-03-21",
    "address": [
        {
            "line": [
                "1948 Bainbridge St"
            ],
            "city": "Philadelphia",
            "state": "PA",
            "postalCode": "19146",
            "country": "US"
        }
    ]
}

The upsert conditionally creates a Patient resource if one does not already exist with that identifier, preventing duplication. Save the ID of the Patient in the response body for the next step.

Create a new job

With a valid Patient resource ID, you can now create a job.

Patient Consent

🚧

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 requestConsent in attributes in the API request body below or by adding an active FHIR Consent resource for the patient.

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

If the job is successfully created, you will receive a 201 Created response status.

Practitioner Identification

Patient History Jobs must be created on behalf of a Practitioner with a valid individual NPI number. If an existing Practitioner FHIR resource is known to you, you can identify the practitioner through the relationships object.

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

If not, the practitioner in attributes allows you to pass in values for NPI, name, and role, which will lookup a Practitioner with those values. If none exist, a Practitioner resource will be created.

❗️

If practitioner is present in both attributes and relationships, you will receive a 400 error.

Schedule a job

You can specify a target date for when a job should be completed. The date or date time must be in RFC3339 format (with a timezone). If no time is specified, it is assumed to be at 12:01 a.m. on the given date. About 32-40 hours before the target, the job will run, ensuring that the job should be completed before the target.

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"
            },
        },
        "targetDate": "2023-09-01T07:00:00Z",
        "relationships": {
            "patient": {
                "data": {
                    "type": "fhir/Patient",
                    "id": "{{ZusPatientID}}"
                }
            }
        }
    }
}

Check the status of a job

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:

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 /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.