Universal Patient Index

Zus' Master Patient Indexing Service

The Universal Patient Index

In healthcare informatics, disparate and duplicative records for patients are a given. Zus offers its own identity mapping service,the Universal Patient Index (UPI), for what is more broadly known as a Master Patient Index. As with other MPI's, patient records submitted to Zus will be compared against all of the patient identities known to Zus, and granted an index key, or Universal Patient Identifier (UPID).

This UPID will be shared across any and all patient records believed to be the same real individual. The sum of all records in our system linked via these UPIDs are referred to here as identities.

We aspire to provide our builders with complete, accurate, and detailed records of all patients in the country by collating and using UPIDs to link together all patient records.


The UPI automatically operates on all patient records in order to build towards a cohesive and national view of patient identities and medical histories.

In order to safeguard the private information of our patients, our matching models err on the side of caution, requiring a surfeit of information in some cases to consider matches viable. UPI performs automatic matching and identity assignment of patient records only when enough information is present and aligned across the novel record and the existing identity.

In cases where UPI strongly suspects a match but cannot confidently assert one, we report a Possible match, which invites you as the originator of the record to manually review, and confirm or deny the match.


As Zus is FHIR-Native, UPI will visit all records you persist as FHIR Patients and attempt to match to identities.

Our UPIDs are for the time being, displayed as universally unique identifier values, or 32 character hexadecimal sequences, e.g. 6738c92e-d3ec-424b-84c1-ffbbb16b3721

These values are written onto the patient record as Identifiers.

Patient records that are matched will have a UPID after the matching is done. This UPID will ideally be the same as an existing identity if we can confidently recognize your patient. If we cannot be certain of a preexisting identity we will create a new identity and key for your patient record.

Merging identities

Should a possible match be confirmed, the UPI will merge together the two identities that have been marked as belonging to the same real individual patient. When matches are rejected, the alien records to the identity will be pulled out and given their own novel identity.

Should more information become available at a later date that bridges the gap between the patient and other identities, we may merge the two identities on your behalf and one UPID value will be subsumed in favor of the other.

Using the UPI through the FHIR Store

Zus automatically leaves the UPID as a breadcrumb on your patient record for you to use without touching the UPI interfaces directly. You could, for instance, query for all patient records who share a UPID in the following manner.


You can construct this query more verbosely and explicitly as well


To view all patients that have a UPID you could query


To view all patients without a UPID you can query


Once you obtain your list of patient IDs, you can use them to say, find all observations pertaining to the same identity via the comma-delimited syntax of our FHIR Store.


You may also be interested in looping through your patients in the same identity and pulling up all contingent data associated to that patient record via the $everything special operation.


UPID Enabled Operations

With a UPID on each of your patient records, you can:

  • Find and manage duplicate records in your system
  • View your complete set of records on a patient
  • Use the UPID to cross-reference populations of records as is commonly done with "roster reconciliations"

In the near future you'll be able to benefit from records in our system originating from outside your own organization as well.

Roster Reconciliation

If you participate in value-based care contracts, you might commonly need to review who you have on file as receiving your care, as compared to your payer's roster of members attributed to you. Misalignments on either side cost you money and given the interoperability challenges between your own organizations structuring of data and your payer's data structure, we hope we can fill a painful gap in your processes by doing the comparisons on your behalf.

In our OpenAPI Specification you should notice the $align endpoint, which does not modify any data, but helps crosswalk how two sets of patient record ID's can be compared using our map of identities.

With two declared sets of patient resource IDs, as FHIR Groups this endpoint will showcase what we are able to identify as being represented across both groups.

Feedback and Trust

We're doing everything we can to build our identities in an accurate and trustworthy manner.

If you believe a patient record of yours has been mistakenly matched to an identity, you can directly break the connection through the APIs described in the OpenAPI specification. Getting in touch with us directly to resolve a mistake on your behalf is always appreciated as well.

If you believe patient records should be linked together and are being given separate UPIDs, you are welcome to get in touch and ask that we learn to support your use case. Our matching process will be iteratively improved upon constantly, and with your help.

Tips for Matching Success

Our matching model will evolve over time as we iterate towards the lowest error and most useful modeling of patient matching. At present, our matching requires a degree of specificity to ensure we're resilient against common pitfalls.

Please provide all patient records with their

  • name
  • date of birth
  • any insurance identifiers available
  • any known contact points (phone number, address, email)

Other available details, like driver’s license numbers, may not be strictly required for matching but increase our ability to correctly and confidently construct a patient's complete medical record on your behalf for your benefit and theirs.

If you do not provide enough information on your patient, the record won’t be able to be placed in the correct identity barring manual intervention on your part.

Johnathan vs Jon

Our matching model will always perform at its best with information that requires no creative comparisons, though it is our goal to model variations in records from organization to organization. The flexibility of our matching models will take time to develop and refine. In the meantime patient records that contain many different avenues of identifying similarity are much likelier at finding an overlapping piece of information in other identities to know definitively whether or not it’s a fit. If your organization and another healthcare provider’s records disagree on a phone number for a patient, having their address agree is enough to compensate in most cases, as an example.

John Doe

Please avoid entering placeholder values for identifying information. Information that is not specific to an individual will actively hamper our attempts at matching them, and may result in incorrect matches.

Zus-Derived Universal Patient Resources

A universal patient resource (“UPI resource”) is Zus’ representation of the 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).