Programming Guide

This guide introduces some basic concepts and workflows that will be important as you begin using the API.

API Workflow

The Identity API workflow involves two basic actions:

• Upload (add or update) patient records.
• Get a complete list of all matching records for an individual.

This enables you to:

• Find all records from your own source system(s) belonging to the same individual (Enterprise MPI).
• Find whether partner organizations (also using the same Identity service) have uploaded records for the same individual, without unnecessary PII exchange (privacy-preserving record linkage).

Uploading Records

When you upload records using the Add/Update Record operation, the system will:

1. Standardize the data to account for common variations in demographics (e.g., phone number formats and nicknames).
2. Perform an irreversible hash on the demographics.
3. Perform a weighted comparison of demographic fields to establish whether the record matches any others in the system, and create links between matching records.
4. Store the hashed record and any associated links.
5. Return the matched person and any MPI changes resulting from the addition or update.

The Identity service associates (or “links”) records via a proprietary algorithm that takes into account subtle differences in formatting (e.g., “1 Main Street” vs “1 Main St.” or “O’Hare” vs “O Hare”), common transpositions, name variations, case variations, and other real-world scenarios. For details, see Understanding Matching.

Only the hashed demographics are stored, making the original values irretrievable in subsequent operations. For more information, see How Identity Secures Data. For added security, you can even use Privacy-Preserving (Blinded) Mode to hash the demographics before they are sent.

Getting Records

When uploading records, you specify where the record originated using a source system and source-specific identifier. For example, when uploading a record from Community Clinic, you might use source name CommunityClinic and Community’s internal database id 12345.

The system assigns a stable Person ID for each unique individual identified. This Person ID is associated with all records for that individual, irrespective of source system.

There are two primary ways to get records associated with an individual:

• Using the Person ID.
• Using the combination of source system and source identifier.

Both will return a list of which source system and identifier are associated with that person. For instance, querying for Person ID f2578ce37ae0 might return:

Notice that you are only getting the list of source systems and identifiers, not the full record with all demographics. The Identity service performs an irreversible hash on the demographics when the record is stored, and thus has no way of returning the original information. It is just an index to tell you where you can find records for that person.

You can also use the Match Demographics operation to find matches for an individual without first uploading their record.

Privacy-Preserving (Blinded) Mode

Within the Identity service, demographic data is irreversibly hashed upon submission. Only the hashed version is stored, and subsequent operations are performed only on the hashed data. For more information, see How Identity Secures Data.

While this system is already highly secure, clients seeking an additional layer of security can use Privacy-Preserving (Blinded) mode to perform the cryptographic hashing operation before the data is even sent.

For more information, see Privacy-Preserving (Blinded) Mode.

Matching Guidance

Although the matching algorithm is extremely reliable, incorrect or incomplete information may cause a missed or incorrect match. You can override links with manual match guidance when it is known that two records represent the same or different individuals.

Retired Records

Due to data updates or record merges, it is possible for Person IDs to become obsolete. When this happens, the Person ID is marked as retired and any records re-associated with other Person IDs. Querying a retired Person ID will indicate that its status is retired, along with the record that superseded it.