ZAP Structure

The ZAP for a patient is a single place where you can see health information from your organization along with information from external data sources aggregated by Zus. With a single API call, you can ensure your care teams can quickly get up to speed on your patient’s health history before the patient even has their first visit.

For example, if you want to review or reconcile a patient’s medications, you can see medications entered by your care team or by your patient (if they completed a Zus form), as well as medications from external sources. These external sources include third party partner networks via the Patient History API, other Builders on Zus treating the same patient, and Zus-summarized and de-duplicated (Lens) medications derived from patient data across all sources, including medications entered by your organization.

You can narrow down what you see in the ZAP by data source. For example, you can limit the ZAP medications your care team users see to only medications created by your Builder, only Zus-summarized (Lens) medications, or any combination of data sources in the diagram above. Zus includes the source of all data points in the ZAP.

Read on for more details on data types in the ZAP, how to query the ZAP, and what is excluded from the ZAP.

What is in the ZAP?

The ZAP for a given patient includes FHIR resources (“resources”) from all sources on Zus, including resources you generate and those generated by other Builders, third party partner networks (e.g., Commonwell, CareQuality, Surescripts), and Zus-summarized (Lens) resources. See documentation for definitions and how to identify these sources for a given resource.

FHIR Resource Types in the ZAP

For a given patient, users and app clients in your Builder can access all resources generated by your Builder, as well as all resources you requested and retrieved from third party partner networks, subject to the permissions in their roles. Lens resources currently exist for MedicationStatements and Conditions only, though there are more resource types in scope on the Zus product roadmap. These additional Lens resources will be available in the ZAP as they are released.

SourceResource Types AvailableAccess Level
Your BuilderAllRead & Write
Third Party Partner NetworksAllRead Only
Lens ResourcesMedicationStatements, ConditionsRead Only
Other Builders on ZusDesignated Record SetRead Only

Zus has also defined a minimum set of resource types for patients as a “Designated Record Set” that your users and app clients can access from other Builders on Zus that have relationships with your patients, without explicit patient consent. This Designated Record Set aligns with the requirements of the 21st Century Cures Act, ONC Information Blocking rules, and HIPAA. See below for the full list of resource types included in the Designated Record Set.

Resource Types in the Designated Record Set:

📘

Zus-Enriched Data

Zus enriches Builder-generated and third party Conditions and Medication-related resources by adding normalized codings (where available) as extensions to these resources. See our Enrichment page to learn more.

Using the ZAP

You have read and write access to patient data your Builder organization created or requested from third party partner networks, subject to the permissions in your user role. If your Builder has a relationship with a patient, you will have read-only access to the resource types from other data sources in the ZAP.

Confirm Relationship with Patient

To access patient data in the ZAP sourced from outside of your Builder, you must make a legally binding assertion that your Builder has a relationship with a patient. You must do this by setting the "active" property on the patient resource to true (boolean type, not string).

Active patient example:

{
    "resourceType": "Patient",
    "active": true,
    "name": [
        {
            "family": "Smith",
            "given": [
                "Mike"
            ]
        }
    ],
...
}

📘

Inactive Patients Included in the ZAP

Other Builders on Zus can view Designated Record Set data for your inactive patients via the ZAP if these Builders have a relationship with the patients.

Make Patient-Centric API Calls

You can access the ZAP by making patient-centric API calls to Zus for one patient at a time, using the Universal Patient Identifier (UPID) to identify the patient. The UPID links together different patient resources across all Builders and sources that Zus’ Universal Patient Index determined represent the same person. You can access Designated Record Set resources associated with all patient resources with the same UPID as the patient resource you created. You can find the UPID on your patient resource in the "identifier" property:

UPID Identifier example:

"identifier": [
    {
        "system": "https://zusapi.com/fhir/identifier/universal-id",
        "value": "<UPID>"
    }
]

Search the Full ZAP

To retrieve all data in a patient's ZAP for a given resource type, filter by the patient's UPID. The API call below will return the four green MedicationStatement resources in the diagram below because they are linked to patient resources sharing the same UPID (123 in the diagram). You can perform this type of query for any resource type in the Designated Record Set.

GET https://api.zusapi.com/fhir/MedicationStatement?patient.identifier=https://zusapi.com/fhir/identifier/universal-id|123

Search My Generated Data Only

To limit ZAP results to only MedicationStatements generated by your Builder, filter on the ID of the patient resource (001 in the diagram above) you previously created for which you want medication data. If you have multiple patient resources you created that refer to the same patient, you must make separate calls filtering on each patient resource.

GET https://api.zusapi.com/fhir/MedicationStatement?patient=001

Search Zus-Summarized (Lens) Data Only

Zus reconciles and summarizes Builder-generated and third party resources in the ZAP as derived Lens resources. To limit ZAP results to only MedicationStatements summarized by Zus, filter on the UPID of the patient (123 in the diagram above) and the Lens ActiveMedications data source tag. This will return only the “Lens Med Statement” in the diagram above.

GET https://api.zusapi.com/fhir/MedicationStatement?patient.identifier=https://zusapi.com/fhir/identifier/universal-id|123&_tag=https://zusapi.com/lens|ActiveMedications

🚧

Include UPID for External Data in the ZAP

You must include a UPID in an API call to access data in a patient's ZAP from other Builders on Zus.

As shown in the example above, making an API call when filtering on a patient resource ID will return data owned by your Builder only for that specific patient resource.

Making calls across multiple UPIDs (see example below) is not currently supported and will return a 403 error.

GET https://api.zusapi.com/fhir/MedicationStatement?patient.identifier=https://zusapi.com/fhir/identifier/universal-id|123,456

API Responses by Search Type and User Role

Searching for a resource without specifying a patient's UPID will not return any resources from other Builders on Zus. Searching for resources outside of the Designated Record Set will not return resources from other Builders on Zus or Lens resources. Patient users are always limited to only data associated with their UPID, so they can never access data for other patients on Zus.

What is NOT in the ZAP?

Restricted Data

Restricted resources in Zus are those that have a FHIR security label with a confidentiality code of “R” for “Restricted” or “V” for “Very Restricted.”

Any resources you tag as restricted in this way CANNOT be seen by other Builders via the ZAP, even if these Builders have a relationship with your patient. See documentation on restricted data for more details.

Add Security Labels to Specially Regulated Data

Currently Zus is NOT automatically applying security labels on behalf of Builders adding patient data to Zus. If you are entering specially regulated data into Zus you must tag it with a security label to prevent it from being visible to other Builders in the ZAP without a patient's consent.

As a reminder, all PHI belongs in the Zus production environment only, NOT the sandbox environment.