JSON Admin Home Endpoint MDM Deprecation Migration

MDM Endpoint
Deprecated

The MDM (Master Data Management) endpoints provide RESTful JSON access to MDM operations through the Admin JSON API. These endpoints offer convenient access to MDM functionality for administrative purposes.

This method requires the ACCESS_ADMIN_JSON permission.

The operations described on this page are DEPRECATED as of 2026.08.PRE and are scheduled for removal in 2028.08.R01 or later. They are flagged deprecated: true in the generated OpenAPI spec. Use the [FHIR MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html) versions on the cdr-endpoint-fhir module instead. See the [JSON Admin API MDM Deprecation Migration](/docs/json_admin_endpoints/mdm_migration.html) guide for the full endpoint mapping. The `mdm-algorithms` and `mdm-metrics` endpoints below are not deprecated.

See FHIR documentation for the FHIR endpoint versions of these MDM endpoints.

MDM Create Link

Creates a new MDM link between an existing golden resource and an existing source resource with the provided match result.

POST http://localhost:9000/mdm/{mdm_module_id}/create-link

Request Body

{
   "goldenResourceId": "Patient/10",
   "resourceId": "Patient/1",
   "matchResult": "MATCH"
}

Response

{
   "links": [{
      "goldenResourceId": "Patient/10",
      "sourceId": "Patient/1",
      "matchResult": "MATCH"
   }]
}

MDM Update Link

Updates an existing MDM link, changing the link relationship between a provided golden resource id and source resource id.

POST http://localhost:9000/mdm/{mdm_module_id}/update-link

Request Body

{
   "goldenResourceId": "Patient/10",
   "resourceId": "Patient/1",
   "matchResult": "MATCH"
}

Response

{
   "links": [{
      "goldenResourceId": "Patient/10",
      "sourceId": "Patient/1",
      "matchResult": "MATCH"
   }]
}

MDM Not Duplicate

Marks the provided golden resources as not duplicates.

Output is always true, or an exception is thrown.

POST http://localhost:9000/mdm/{mdm_module_id}/not-duplicate

Request Body

{
   "goldenResourceId": "Patient/10",
   "resourceId": "Patient/1"
}

Response

true

MDM Merge Golden Resources

Merges one golden resource into another. After the merge is complete, the "from" golden resource will be deactivated.

POST http://localhost:9000/mdm/{mdm_module_id}/merge-golden-resources

Request Body

{
   "fromGoldenResourceId": "Patient/10",
   "toGoldenResourceId": "Patient/20"
}

Response

{
   "resourceType": "Patient",
   "id": "20",
   "meta": {
      "versionId": "2",
      "lastUpdated": "2000-01-31T00:00:00.000-00:00",
      "tag": [
         {
            "system": "http://hapifhir.io/fhir/NamingSystem/mdm-record-status",
            "version": "1",
            "code": "GOLDEN_RECORD",
            "display": "Golden Record",
            "userSelected": false
         },
         {
            "system": "https://hapifhir.org/NamingSystem/managing-mdm-system",
            "version": "1",
            "code": "HAPI-MDM",
            "display": "This Golden Resource can only be modified by HAPI MDM system.",
            "userSelected": false
         }
      ]
   },
   "identifier": [
      {
         "system": "http://hapifhir.io/fhir/NamingSystem/mdm-golden-resource-enterprise-id",
         "value": "4f8d1113-6a76-4671-88cd-10f7dc3bd2e6"
      },
      {
         "system": "http://hapifhir.io/fhir/NamingSystem/mdm-golden-resource-enterprise-id",
         "value": "799fec0d-7904-4698-bc7d-3cf6dd757c30"
      }
   ]
}

MDM Query Links

Returns a pageable list of MDM links that fit the optionally provided query parameters.

GET http://localhost:9000/mdm/{mdm_module_id}/query-links?matchResult=NO_MATCH

Query Parameters

goldenResourceId - A single string value of the golden resource id. E.g.: goldenResourceId=Patient%2F10
resourceId - A single string value of the source resource id. E.g.: resourceId=Patient%2F1
matchResult - A string value of the match type of interest (MATCH, NO_MATCH, POSSIBLE_MATCH). E.g.: matchResult=MATCH
linkSource - A single string of the link type (AUTO, MANUAL). E.g.: linkSource=AUTO
_offset - Offset for paging. E.g.: _offset=1
_count - The number of links to return. E.g.: _count=10
_sort - One or more comma separated string values indicating the fields of the MDM Link on which to sort (prefaced with a - for descending order). E.g.: sort=-myUpdated
resourceType - The resource types of interest. E.g.: resourceType=Patient
partitionIds - A list of partition ids to search. E.g.: partitionIds=1,2,3

Response

{
   "links": [
      {
         "goldenResourceId": "Patient/10",
         "sourceId": "Patient/1",
         "matchResult": "MATCH",
         "linkSource": "AUTO",
         "created": 1691003284116,
         "updated": 1691003284116,
         "version": "1",
         "eidMatch": false,
         "vector": 0,
         "score": 1.0,
         "ruleCount": 0,
         "linkCreatedNewGoldenResource": true
      }
   ]
}

MDM Link History

Shows a history for a given set of MDM links, querying by golden resource IDs, source IDs, or both.

GET http://localhost:9000/mdm/{mdm_module_id}/link-history?goldenResourceId=Patient/10

Query Parameters

The following query parameters are available. One or both must be provided:

goldenResourceId - The golden resource id of interest. E.g.: goldenResourceId=Patient/10
resourceId - The source resource id of interest. E.g.: resourceId=Patient/1

Response

{
   "links": [
      {
         "mdmLink": {
            "goldenResourceId": "Patient/10",
            "sourceId": "Patient/1",
            "matchResult": "MATCH",
            "linkSource": "AUTO",
            "created": 1691003284116,
            "updated": 1691003284116,
            "version": "1",
            "eidMatch": false,
            "vector": 0,
            "score": 1.0,
            "ruleCount": 0,
            "linkCreatedNewGoldenResource": true
         },
         "revisionNumber": 1,
         "revisionTimestamp": 1691003284123
      }
   ]
}

MDM Duplicate Golden Resources

Returns a list of all the duplicate golden resources.

GET http://localhost:9000/mdm/{mdm_module_id}/duplicate-golden-resources

Query Parameters

The following optional query parameters are available:

_offset - The offset to begin returning records at. E.g.: _offset=1
_count - The number of resources to be returned per page. E.g.: _count=10
partitionIds - A list of partitions to query. E.g.: partitionIds=1,2,3
resourceType - The resource type of interest. E.g.: resourceType=Patient

Response

{
   "links": [
      {
         "goldenResourceId": "Patient/10",
         "sourceId": "Patient/1",
         "matchResult": "POSSIBLE_DUPLICATE",
         "linkSource": "AUTO",
         "created": 1691003284116,
         "updated": 1691003284116,
         "version": "1",
         "eidMatch": false,
         "vector": 0,
         "score": 1.0,
         "ruleCount": 0,
         "linkCreatedNewGoldenResource": true
      }
   ]
}

MDM Submit

Submits a batch job to perform MDM matching on all existing resources in the system. An optional criteria can be provided to filter resources on which to match.

The output value will be the number of resources submitted for MDM processing.

POST http://localhost:9000/mdm/{mdm_module_id}/mdm-submit

Request Body

{
   "resourceType": "Patient",
   "criteria": "birthdate=2020-07-28"
}

Response

MDM Clear

Bulk deletes all MDM links and related golden resources from the system. Supports both asynchronous (default) and synchronous execution modes.

POST http://localhost:9000/mdm/{mdm_module_id}/mdm-clear

Execution Modes

Asynchronous mode (default): When no Prefer header is present (or when Prefer: respond-async is used), the operation submits a Batch2 background job and immediately returns a job ID. The caller can monitor job progress via the admin console. This is the default behavior for backwards compatibility.

Synchronous mode: When the Prefer: wait=n HTTP header is present (where n is the number of seconds the client is willing to wait), the operation executes inline without creating a Batch2 job. If the operation completes within the wait window, it returns 200 OK with a result summary. If the operation cannot complete in time, it returns 202 Accepted and continues processing in the background; the only way to confirm completion in this case is by checking the server logs.

Synchronous mode is subject to the following constraint: if the total number of MDM links in the system exceeds 10,000, the operation immediately rejects the request with 422 Unprocessable Entity. This prevents long-running synchronous deletes from impacting system performance. In that case, resubmit without the Prefer: wait=n header to run asynchronously.

Request Headers

Header	Description
`Prefer: wait=n`	(Optional) Request synchronous execution, where `n` is the number of seconds the client is willing to wait. If omitted, the operation runs asynchronously (same as `Prefer: respond-async`).
`Prefer: respond-async`	(Optional) Explicitly request asynchronous execution. This is the default behavior when no `Prefer` header is provided.

Request Body

{
   "resourceType": "Patient,Practitioner",
   "batchSize": 500,
   "tenantId": "{tenant-id}"
}

Note: batchSize and tenantId are optional. When resourceType is omitted, all MDM-enabled resource types are cleared.

Response — Asynchronous (no Prefer header)

HTTP 200 OK

{
   "resourceType": "Parameters",
   "parameter": [{
      "name": "jobId",
      "valueString": "some-guid-value"
   }]
}

Response — Synchronous (Prefer: wait=n)

HTTP 200 OK

{
   "resourceType": "Parameters",
   "parameter": [
      {
         "name": "status",
         "valueString": "COMPLETED"
      },
      {
         "name": "resourcesCleared",
         "valueInteger": 42
      }
   ]
}

Response — Synchronous timeout (Prefer: wait=n expired)

HTTP 202 Accepted

{
   "resourceType": "Parameters",
   "parameter": [
      {
         "name": "status",
         "valueString": "IN_PROGRESS"
      },
      {
         "name": "message",
         "valueString": "The $mdm-clear operation is still running in the background. Check server logs for completion status."
      }
   ]
}

Response — Synchronous rejected (link count > 10,000)

HTTP 422 Unprocessable Entity

{
   "resourceType": "OperationOutcome",
   "issue": [{
      "severity": "error",
      "diagnostics": "Cannot process $mdm-clear synchronously: 15000 MDM links exceed the 10000 link limit. Resubmit without the Prefer: wait=n header to run asynchronously."
   }]
}

MDM Metrics

Returns metrics about the MDM module.

GET http://localhost:9000/mdm/{mdm_module_id}/mdm-metrics?resourceType=Patient

Query Parameters

resourceType (required) - The resource type of interest. Must be a valid FHIR resource type. E.g.: resourceType=Patient

matchResult (optional) - A string value of the match type of interest (MATCH, NO_MATCH, POSSIBLE_MATCH). Metrics (for score and link type counts) will be filtered to only look at the provided match results. If none are provided, all will be checked. E.g.: matchResult=MATCH

linkSource (optional) - A single string of the link type (AUTO, MANUAL). Metrics for link type counts will be filtered to only look at the provided link sources. If none are provided, all will be checked. E.g.: linkSource=AUTO

partitionIds (optional) - A list of partition ids to scope the metrics to. E.g.: partitionIds=1,2,3. This parameter is ignored when the MDM module is configured with MDM_SEARCH_ALL_PARTITION_FOR_MATCH set to true, in which case metrics aggregate across all partitions. When MDM_SEARCH_ALL_PARTITION_FOR_MATCH is false (the default) and no partition ids are supplied, the request runs against the default single-partition context.

Response Example 1

{
	"resourceType": "Patient",
	"matchResult2linkSource2count": {
		"NO_MATCH": {
			"MANUAL": 1
		},
		"MATCH": {
			"AUTO": 5
		}
	},
	"scoreCounts": {
		"NULL": 0,
		"x_<_0.01": 0,
		"0.01_<_x_<=_0.02": 0,
		"0.02_<_x_<=_0.03": 0,
		"0.03_<_x_<=_0.04": 0,
		"...": "...",
		"0.97_<_x_<=_0.98": 0,
		"0.98_<_x_<=_0.99": 0,
		"0.99_<_x_<=_1.00": 6
	},
	"goldenResources": 4,
	"sourceResources": 5,
	"excludedResources": 0
}

Response Example 2

For filtered results using matchResult=MATCH&linkSource=AUTO:

{
	"resourceType": "Patient",
	"matchResult2linkSource2count": {
		"MATCH": {
			"AUTO": 5
		}
	},
	"scoreCounts": {
		"NULL": 0,
		"x_<_0.01": 0,
		"0.01_<_x_<=_0.02": 0,
		"0.02_<_x_<=_0.03": 0,
		"0.03_<_x_<=_0.04": 0,
		"...": "...",
		"0.97_<_x_<=_0.98": 0,
		"0.98_<_x_<=_0.99": 0,
		"0.99_<_x_<=_1.00": 5
	},
	"goldenResources": 4,
	"sourceResources": 5,
	"excludedResources": 0
}

Notes

This operation is currently only supported on the JSON Admin API
This operation is currently in experimental stage and may be subject to change with minimal notice

JSON Admin Home Endpoint MDM Deprecation Migration

MDM EndpointDeprecated

Request Body

Response

Request Body

Response

Request Body

Response

Request Body

Response

Query Parameters

Response

Query Parameters

Response

Query Parameters

Response

Request Body

Response

Execution Modes

Request Headers

Request Body

Response — Asynchronous (no Prefer header)

Response — Synchronous (Prefer: wait=n)

Response — Synchronous timeout (Prefer: wait=n expired)

Response — Synchronous rejected (link count > 10,000)

Query Parameters

Response Example 1

Response Example 2

MDM Endpoint
Deprecated