This guide introduces some basic concepts and workflows that will be important as you begin using the API.
Contents
The Identity API workflow involves two basic actions:
This enables you to:
When you upload records using the Add/Update Record operation, the system will:
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.
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:
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:
Source | Identifier |
---|---|
CommunityClinic | 12345 |
AnytownUrgentCare | AZ67889 |
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.
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.
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.
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.