Find duplicates: $match

The $match operation is used to find potential duplicate patient records.

It performs a probabilistic search based on a matching model that compares the patient record you provide with other patient records in the system across multiple features and estimates how similar they are. The structure of the matching model and its parameters are described on the Matching Model Explanation page.

The result is a list of potential duplicates, each with a calculated match score and a detailed breakdown of feature similarity.

This page provides key information about using $match. For full API details, refer to our Swagger documentation .

$match

The match operation can be initiated either through the MPI user interface or by using the API.

The $match operation supports several query parameters that let you control how matching is performed and how results are returned:

To call the $match operation, you have to send a FHIR Parameters resource that includes the patient record for which you want to search potential duplicates. Typically, this record contains demographic data such as:

• Name (given and family)
• Address (e.g., city, state)
• Birth date
• Other identifying attributes if available (e.g., telecom, identifiers)

For example, the request can looks like this:

POST /fhir/Patient/$match?model=model&threshold=10&page=1&size=10
Content-Type: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "resource",
      "resource": {
        "name": [
          {
            "given": [
              "Freya"
            ],
            "family": "Shah"
          }
        ],
        "address": [
          {
            "city": "London"
          }
        ],
        "birthDate": "1970-12-17"
      }
    }
  ]
}

As a result, you will receive the following:

• A list of candidate duplicate patient records
• For each candidate record:
  • match_weight — an overall similarity score calculated by the matching model
  • match_details — per-feature similarity contributions (e.g., name similarity, date of birth match, address closeness, etc.)
  • resource — the full FHIR Patient resource for that candidate

The response is sorted by match_weight in descending order so that the most similar records appear first.

For example:

[
  {
    "match_details": {
      "fn": 13.336495228175629,
      "dob": 10.59415069916466,
      "ext": -10.517360697819983,
      "sex": 0
    },
    "match_weight": 13.413285229520307,
    "resource": {
      "id": "236",
      "resourceType": "Patient",
      "name": [
        {
          "given": [
            "Freya"
          ],
          "family": "Shah"
        }
      ],
      "address": [
        {
          "city": "Londodn"
        }
      ],
      "birthDate": "1970-12-17",
      "identifier": [
        {
          "value": "62",
          "system": "cluster"
        }
      ]
    }
  },
  {
    "match_details": {
      "fn": 13.336495228175629,
      "dob": 10.59415069916466,
      "ext": -10.517360697819983,
      "sex": 0
    },
    "match_weight": 13.413285229520307,
    "resource": {
      "id": "242",
      "resourceType": "Patient",
      "name": [
        {
          "given": [
            "Freya"
          ],
          "family": "Shah"
        }
      ],
      "address": [
        {
          "city": "Lonnod"
        }
      ],
      "birthDate": "1970-12-17",
      "identifier": [
        {
          "value": "62",
          "system": "cluster"
        }
      ]
    }
  },
  {
    "match_details": {
      "fn": 13.104401641242227,
      "dob": 10.59415069916466,
      "ext": -10.517360697819983,
      "sex": 0
    },
    "match_weight": 13.181191642586905,
    "resource": {
      "id": "238",
      "resourceType": "Patient",
      "name": [
        {
          "given": [
            "Shah"
          ],
          "family": "Freya"
        }
      ],
      "address": [
        {
          "city": "London"
        }
      ],
      "telecom": [
        {
          "value": "f.s@flynn.com",
          "system": "email"
        }
      ],
      "birthDate": "1970-12-17",
      "identifier": [
        {
          "value": "62",
          "system": "cluster"
        }
      ]
    }
  }
]