MDM API Operations

This page is a reference for the FHIR operations exposed by the MDM module.

$match

This operation finds and returns any Patient records that match a provided resource according to the configured matching rules.

POST /Patient/$match

$mdm-match

This operation finds and returns any records of a requested type that match a provided resource according to the configured matching rules. Unlike $match, this operation does not require the provided resource to be a Patient.

POST /$mdm-match

$mdm-submit

This operation triggers MDM processing for existing resources. It can target all resources of the configured MDM types, a specific resource type (optionally filtered by a FHIR search criteria string), or individual resource instances. By default the operation runs synchronously and returns a count of submitted resources. To run asynchronously, include a Prefer: respond-async HTTP header.

POST /$mdm-submit
POST /Patient/$mdm-submit
POST /Practitioner/$mdm-submit
POST /Patient/{id}/$mdm-submit
POST /Practitioner/{id}/$mdm-submit

$sdh.mdm-bundle-match

This operation accepts a Bundle of resources and matches each entry against the repository using the configured MDM rules, removing or merging duplicate resources before the bundle is stored. It is the basis of the deduplication on ingestion strategy.

POST /Bundle/$sdh.mdm-bundle-match

This operation is documented in detail, including its parameters, permissions and examples, in $sdh.mdm-bundle-match Operation.

$mdm-create-link

This operation manually creates a new MDM link between a golden resource and a source resource.

A single source resource may not have links with match result MATCH targeting multiple golden resources. If the source resource already has such a link, any attempt to create a second one is rejected.

POST /$mdm-create-link

$mdm-update-link

This operation manually sets the match result on an existing MDM link between a golden resource and a source resource. The match result must be either MATCH or NO_MATCH.

A single source resource may not have links with match result MATCH targeting multiple golden resources. If the source resource already has such a link, any attempt to update another link to MATCH is rejected.

POST /$mdm-update-link

$mdm-query-links

This operation queries and returns MDM links, optionally filtered by golden resource ID, source resource ID, match result, link source, or resource type. Results are paginated.

GET /$mdm-query-links

$mdm-link-history

This operation returns the historical record of changes made to MDM links associated with specified golden resource IDs or source resource IDs. At least one of goldenResourceId or resourceId must be provided.

GET /$mdm-link-history

$mdm-clear

This operation removes MDM links and their associated golden resources for the specified resource types, resetting the MDM state. This is an asynchronous operation by default. To request synchronous execution, include a Prefer: wait=<seconds> HTTP header; the response will be synchronous if it completes within the specified time, or asynchronous otherwise.

POST /$mdm-clear

$mdm-duplicate-golden-resources

This operation returns pairs of golden resources that the MDM system has identified as potential duplicates. Results are paginated.

GET /$mdm-duplicate-golden-resources

$mdm-not-duplicate

This operation marks two golden resources as intentionally not duplicates of each other. After this operation the pair will no longer appear in $mdm-duplicate-golden-resources results.

POST /$mdm-not-duplicate

$mdm-merge-golden-resources

This operation merges two golden resources into one. The source golden resource (fromGoldenResourceId) is deactivated and all of its MDM links are transferred to the target golden resource (toGoldenResourceId). An optional merged resource body may be supplied to control survivorship of field values on the resulting golden resource.

This operation acts on Golden Resources and their links; the source records themselves are not modified. To merge the underlying source records, use the repository-level $merge and $hapi.fhir.merge operations described in Working with Duplicates.

POST /$mdm-merge-golden-resources

$mdm-evaluate

This operation tests a single MDM matching or similarity algorithm against two input values and returns whether they match and, for similarity algorithms, a numeric score. This is useful for tuning MDM rules.

GET /$mdm-evaluate

This operation is documented in detail, including its parameters, permissions and examples, in $mdm-evaluate Operation.