Understanding Record Groups

This tutorial demonstrates how you can add and update records in the BMPI, 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.

Adding John’s First Record

In order for the BMPI to be able to match source demographics to one another, they must first be added to the BMPI 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 to the BMPI:

POST /mpi/v1/record/CommunityClinic/12345

{
  "firstName":"John",
  "lastName":"Smith",
  "gender":"male",
  "dob":"1/2/2003",
  "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.

This request will result in a response like:

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

This indicates that the BMPI 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 to the BMPI:

POST /mpi/v1/record/AnytownUrgentCare/55678

{
  "firstName":"Jon",
  "lastName":"Smith",
  "dob":"1/2/2003",
  "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 (55678). 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": "55678"
            }
        ],
        ...
}

Because the demographic information from Anytown is limited and inconsistent, the BMPI 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 BMPI using the same API operation:

POST /mpi/v1/record/AnytownUrgentCare/55678

{
  "firstName":"Jon",
  "lastName":"Smith",
  "dob":"1/2/2003",
  "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 BMPI 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": "55678"
            }
        ],
        "version": 2,
        "status": {
            "code": "Active",
            "supersededBy": []
        }
    },
    "changedPersons": [
        {
            "id": "463091ba-6629-4800-9b23-b30a83f16ab6",
            "records": [
                {
                  "source": "AnytownUrgentCare",
                  "identifier": "55678"
                }
            ],
            "version": 1,
            "status": {
                "code": "Retired",
                "supersededBy": [
                    "a46ee8bd-9dd1-41e6-bced-f2578ce37ae0"
                ]
            }
        }
    ]
}

Note that a few things happened under the hood:

  1. The response retains the Person ID associated with the oldest record. In this case, that’s the one from the first Community record (a46e...).
  2. 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.