Compare Records

POST /mpi/v1/records/compare

The Compare Records operation can help you understand why two different records were (or weren’t) linked by examining the field differences between them.

Contents

Field Similarity
Example
Query Parameters
Response Data

Field Similarity

Fields are categorized as one of the following based on similarity:

Exact Match
High Similarity
Low Similarity
Different

See Demographic Weighting and Match Confidence for more information on match similarities.

Example

For example, considering the following operation comparing two records from CommunityClinic and AnytownUrgentCare:

/mpi/v1/records/compare?sourceA=CommunityClinic&identifierA=12345&sourceB=AnytownUrgentCare&identifierB=AZ67889

The compare operation will return the complete person data corresponding to these two records. This shows whether the records are linked, and any other linked records. It also shows a detailed breakdown comparing the field similarity between the two records.

From this comparison, we can see that the two records had the same Last Name and Health Card ID, and that the First Names were highly similar. However, the date of birth was different, and recordA (CommunityClinic) was missing fields like gender and address.

Sample Comparison

    "comparison": {
        "exactFields": [
            "LastName",
            "HCID"
        ],
        "highSimilarityFields": [ "FirstName" ],
        "lowSimilarityFields": [],
        "differentFields": [ "DOB" ],
        "recordAMissingFields": [
            "Gender",
            "State",
            "City",
            "StreetType",
            "StreetName",
            "StreetNumber",
            "ZipCode",
        ],
        "recordBMissingFields": []
    },
  "comparison": {
        "exactFields": [
            "LastName",
            "HCID"
        ],
        "highSimilarityFields": [ "FirstName" ],
        "lowSimilarityFields": [],
        "differentFields": [ "DOB" ],
        "recordAMissingFields": [
            "Gender",
            "State",
            "City",
            "StreetType",
            "StreetName",
            "StreetNumber",
            "ZipCode",
        ],
        "recordBMissingFields": []
    },

Query Parameters

sourceA string

The source system for the first record.

identifierA string

The unique identifier, within the source system, for the first record.

sourceB string

The source system for the second record.

identifierB string

The unique identifier, within the source system, for the second record.

Response Data

recordA object

Identifies the first record.

Child Fields

recordA.source string

A source system with an internal means of identifying individuals.

recordA.identifier string

The unique identifier of the record within the source. This will be stored directly in the Identity service (not hashed or encrypted), so consider what kind of identifiers are suitable to your use case.

recordB object

Identifies the second record.

Child Fields

recordB.source string

A source system with an internal means of identifying individuals.

recordB.identifier string

personA object

Full details for the matched person associated with recordA, including all other linked records.

Child Fields

personA.id string

The stable identifier for this person used across records (“Person ID”).

personA.records collection

The constituent records that represent this person.

Element Fields

personA.records[n].source string

A source system with an internal means of identifying individuals.

personA.records[n].identifier string

personA.version integer

As records are added or removed, this version number will be incremented.

personA.status object

Child Fields

personA.status.code string

One of: Active or Retired. A record is retired when the original record has been superseded by new record(s).

personA.status.supersededBy string[]

If the person’s constituent records were merged into another person (or persons), this will contain a list of the IDs for the person(s).

personB object

Full details for the matched person associated with recordB, including all other linked records.

Child Fields

personB.id string

The stable identifier for this person used across records (“Person ID”).

personB.records collection

The constituent records that represent this person.

Element Fields

personB.records[n].source string

A source system with an internal means of identifying individuals.

personB.records[n].identifier string

personB.version integer

As records are added or removed, this version number will be incremented.

personB.status object

Child Fields

personB.status.code string

One of: Active or Retired. A record is retired when the original record has been superseded by new record(s).

personB.status.supersededBy string[]

If the person’s constituent records were merged into another person (or persons), this will contain a list of the IDs for the person(s).

comparison object

Summarizes the field comparisons between the records.

Child Fields

comparison.exactFields string[]

A list of fields that matched exactly.

comparison.highSimilarityFields string[]

A list of fields that had high similarity.

comparison.lowSimilarityFields string[]

A list of fields that had low similarity.

comparison.differentFields string[]

A list of fields that were different.

comparison.recordAMissingFields string[]

A list of fields missing from recordA.

comparison.recordBMissingFields string[]

A list of fields missing from recordB.

currentAsOf date

When the records were last updated.