Understanding Record Groups

This tutorial demonstrates how you can add and update records using the Identity API, and helps you understand how those records are associated with Person IDs to create record groups. This article does not cover the specifics of what criteria are used to link the records, but focuses on what happens once they are linked. For more information on the matching algorithm, see Understanding Matching.

Contents

Adding John’s First Record
Adding a Variant Record for John
Updating John’s Variant Record

Adding John’s First Record

In order for the Identity service to match source demographics to one another, they must first be added using the Add or Update Record operation.

The first record we have for John Smith is some data from Community Clinic, which we can add using:

POST /mpi/v1/record/CommunityClinic/12345

{
  "firstName":"John",
  "lastName":"Smith",
  "gender":"male",
  "dob":"2003/01/02",
  "street":"123 Shady Lane",
  "city":"Anytown",
  "zipCode":"48105"
}

The record is identified by the source (CommunityClinic) and an internal identifier from that source (12345) in the URL parameters. Records about other individuals from “Community Clinic” should use the same source string and different internal identifiers.

Note
This source identifier will be stored directly (unhashed/unblinded) by the Identity service, and should always be an internal ID such as a database primary key. Never use a business identifier (e.g., SSN, MRN, or insurance policy number) as the source identifier.

Tip
For the automated patient matching to be most effective, always include all available demographic information.

This request will result in a response like:

{
    "matchedPerson": {
        "id": "a46ee8bd-9dd1-41e6-bced-f2578ce37ae0",
        "records": [
            {
                "source": "CommunityClinic",
                "identifier": "12345"
            }
        ],
        ...
}

This indicates that the Identity service has created the Person ID a46e..., and associated it with John Smith’s Community Clinic Record.

Adding a Variant Record for John

Later, we receive data from a different source about John, this time from Anytown UrgentCare. Unfortunately, Anytown has a variant of his name (“Jon Smith”) and a different address. We can still add this record using:

POST /mpi/v1/record/AnytownUrgentCare/AZ67889

{
  "firstName":"Jon",
  "lastName":"Smith",
  "gender":"male",
  "dob":"2003/01/02",
  "street":"567 Sunny Cir"
}

Since this is from a different data source, the post uses a new source string (AnytownUrgentCare) and an Anytown-specific internal identifier (AZ67889). Different source systems will generally use different identifiers, but even if they don’t, records are always referenced by the combination of source system and identifier.

This request will result in a response like:

{
    "matchedPerson": {
        "id": "463091ba-6629-4800-9b23-b30a83f16ab6",
        "records": [
            {
                "source": "AnytownUrgentCare",
                "identifier": "AZ67889"
            }
        ],
        ...
}

Because the demographic information from Anytown is limited and inconsistent, the Identity service has concluded that the records are not sufficiently similar to result in an automatic link. The system creates a new Person ID (4630...), and associates it with John’s Anytown record.

Updating John’s Variant Record

John returns to Anytown Urgent Care, and this time updates his address due to a recent move. We can update his information in the Identity service using the same API operation:

POST /mpi/v1/record/AnytownUrgentCare/AZ67889

{
  "firstName":"Jon",
  "lastName":"Smith",
  "gender":"male",
  "dob":"2003/01/02",
  "street":"123 SHADY LN"
}

This update to John’s street address is now consistent (apart from some formatting variance) with the record from Community Clinic. The Identity service now has sufficient information to determine that both records are from the same John Smith.

This update will result in a response that includes both John’s Community Clinic and Anytown Urgent Care records:

{
    "matchedPerson": {
        "id": "a46ee8bd-9dd1-41e6-bced-f2578ce37ae0",
        "records": [
            {
                "source": "CommunityClinic",
                "identifier": "12345"
            },
            {
                "source": "AnytownUrgentCare",
                "identifier": "AZ67889"
            }
        ],
        "version": 2,
        "status": {
            "code": "Active",
            "supersededBy": []
        }
    },
    "changedPersons": [
        {
            "id": "463091ba-6629-4800-9b23-b30a83f16ab6",
            "records": [
                {
                  "source": "AnytownUrgentCare",
                  "identifier": "AZ67889"
                }
            ],
            "version": 1,
            "status": {
                "code": "Retired",
                "supersededBy": [
                    "a46ee8bd-9dd1-41e6-bced-f2578ce37ae0"
                ]
            }
        }
    ]
}

Note that a few things happened under the hood:

The response retains the Person ID associated with the oldest record. In this case, that’s the one from the first Community record (a46e...).
The Person ID associated with the original Anytown record (4630...) has been retired, and all of its records moved to the a46e... Person ID. This is indicated by the changedPersons field. Future queries of the 4630... Person ID will return a status of Retired, with the supersededBy field pointing to the correct Person ID.