How Zus Uses FHIR

This guide covers the types of data available in Zus and how to identify them.

Builder-Generated Resources

Builder-generated resources are FHIR resources (“resources”) that a user or app client creates. Generally, the Builder that creates the resource is the “owner,” as evidenced by an Access Control Tag. “Access Control Tags” are meta tags generated by Zus for tracking resource owners. Users have access to resources their Builder owns, subject to the permissions specified in their user role.

Access Control Tag example:

"meta": {
    "tag": [
        {
            "system": "https://zusapi.com/accesscontrol/owner",
            "code": "builder/<BuilderID>",
            "display": "Builder Name"
        }
    ]
}

❗

Access Control Tag Permissions

Only Zus has the ability to create, modify, or delete Access Control Tags.

If a user attempts to create, modify, or delete an Access Control Tag in the process of creating or modifying a resource, the creation or modification operation on the resource will proceed, but any Access Control Tag changes will not be recognized by Zus (i.e., an error response will not be returned).

Users can only read tags for resources they have permission to see.

Third Party Resources

Third party patient data are data ingested from Zus' third party partner networks, including but not limited to, CommonWell, CareQuality, and SureScripts, using the Patient History API. You can identify whether a given resource originated from a third party partner network by the presence of a “Third Party Tag,” which is a meta tag generated by Zus.

Third Party Tag example:

"meta": {
    "tag": [
        {
            "system": "https://zusapi.com/thirdparty/source",
            "code": "surescripts"
        }
    ]
}

❗

Third Party Permissions

Builder users and app clients are NOT permitted to create, modify, or delete third party resources. Any attempt to do so will result in a 403 error.

Zus-Enriched Resources

Zus enriches Builder-generated and third party Conditions and Medication-related resources in the Zus Aggregated Profile (ZAP) by adding normalized codings (where available) as resource extensions. See our Enrichment page for more details and examples of enriched resources.

📘

Zus Aggregated Profile (ZAP)

The ZAP for a patient is a single place where you can see health information from your organization along with information from external sources on the Zus network. See here for more detail on how to query the ZAP.

Builder users can create, modify, and delete Zus-enriched resources as permitted by the permissions in their user role.

Zus-Derived Lens Resources

Lens resources are aggregated, summarized versions of Builder-generated and third party resources in the Zus Aggregated Profile (ZAP). You can identify a Lens resource by the presence of a “Lens Tag,” which is a meta tag generated by Zus. See our Lens documentation for more detail on all types of Lenses.

Lens Tag example:

"meta": {
    "tag": [
        {
            "system": "https://zusapi.com/lens",
            "code": "ActiveMedications"
        }
    ]
}

❗

Lens Permissions

Builder users and app clients are NOT permitted to create, modify, or delete Lens resources. Any attempt to do so will result in a 403 error.

Zus-Derived Universal Patient Resources

A universal patient resource (“UPI resource”) is Zus’ representation of a patient’s identity. Zus creates and manages UPI resources by drawing on all patient resources across all data sources in Zus that resolve to the same person. You can identify a UPI resource by the presence of a “UPI Tag,” which is a meta tag generated by Zus.

UPI Tag example:

"meta": {
    "tag": [
        {
            "system": "https://zusapi.com/fhir/tag/upi-record-type",
            "code": "universal"
        }
    ]
}

❗

UPI Resource Permissions

Builder users and app clients are NOT permitted to create, modify, or delete UPI resources. Any attempt to do so will result in a 403 error.

Each UPI resource has a unique identifier (“UPID”) which is assigned to every patient resource in Zus shortly after each patient resource is created. If UPI's matching model determines that two patient resources represent the same person, UPI will add the same UPID as an additional identifier on each patient resource to indicate that both patient resources refer to the same person.

UPI Identifier example on patient resource:

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

UPI also adds this UPID on all resources in the Designated Record Set linked to a patient resource with this UPID.

UPI Identifier example on Designated Record Set resource:

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

❗

UPI Identifier Permissions

Builder users and app clients are NOT permitted to create, modify, or delete UPI identifiers. Any attempt to do so will not be recognized by Zus (i.e., an error response will not be returned).

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

Restricted tag example:

"meta": {
    "security": [
        {
            "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
            "code": "R",    
            "display": "Restricted"
        }
    ]
}

Any resources tagged as restricted in this way CANNOT be seen by other Builders via the Zus Aggregated Profile (ZAP), even if these Builders have a relationship with your patient. Users and app clients are permitted to view restricted resources if these resources are owned by their Builder or are owned by a Builder that has granted them cross-builder access.

Any specially regulated data entered into Zus must be tagged as restricted so that such data are not accessible to other Builders. Specially regulated data are a subset of PHI that may not be shared among providers without consent from the patient (e.g., HIV status, psychotherapy notes, substance use, mental health facility information). Data may be specially regulated at the US state level and/or at the federal level.

❗

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 a user or app client enters specially regulated data into Zus, they 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.

Test Data

To test your workflows and applications on Zus, you can create test resources. To distinguish these test resources from your real production data, you must tag them with the “HTEST” code in a security label. There are currently no restrictions on the use of this HTEST tag.

HTEST tag example:

"meta": {
    "security": [
        {
            "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
            "code": "HTEST",
            "display": "test health data" 
        }
    ]
}