Merge Example 1: Merge Patient/2 into Patient/3 synchronously.

Input:

POST /Patient/$merge
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source-patient",
      "valueReference": {
        "reference": "Patient/2"
      }
    },
    {
      "name": "target-patient",
      "valueReference": {
        "reference": "Patient/3"
      }
    }
  ]
}

Output:

HTTP/1.1 200 OK

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "input",
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          {
            "name": "source-patient",
            "valueReference": {
              "reference": "Patient/2"
            }
          },
          {
            "name": "target-patient",
            "valueReference": {
              "reference": "Patient/3"
            }
          }
        ]
      }
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "details": {
              "text": "Merge operation completed successfully."
            }
          }
        ]
      }
    },
    {
      "name": "result",
      "resource": {
        "resourceType": "Patient",
        "id": "3",
        "identifier": [
          {
            "system": "SYS2A",
            "value": "VAL2A"
          },
          {
            "system": "SYS2B",
            "value": "VAL2B"
          },
          {
            "system": "SYSC",
            "value": "VALC"
          },
          {
            "use": "old",
            "system": "SYS1A",
            "value": "VAL1A"
          },
          {
            "use": "old",
            "system": "SYS1B",
            "value": "VAL1B"
          }
        ],
        "link": [
          {
            "other": {
              "reference": "Patient/2"
            },
            "type": "replaces"
          }
        ]
      }
    }
  ]
}

Merge Example 2: Preview merge Patient/2 into Patient/3 synchronously.

Input:

POST /Patient/$merge
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source-patient",
      "valueReference": {
        "reference": "Patient/2"
      }
    },
    {
      "name": "target-patient",
      "valueReference": {
        "reference": "Patient/3"
      }
    },
    {
      "name": "preview",
      "valueBoolean": true
    }
  ]
}

Output:

HTTP/1.1 200 OK

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "input",
      "resource": {
        "resourceType": "Parameters",
        ...copy of input...
      }
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "details": {
              "text": "Preview only merge operation - no issues detected"
            },
            "diagnostics": "Merge would update 25 resources"
          }
        ]
      }
    },
    {
      "name": "result",
      "resource": {
        "resourceType": "Patient",
        ...merged patient...
      }
    }
  ]
}

Merge Example 3: Merging Patients by identifier asynchronously.

Input:

POST /Patient/$merge
Content-Type: application/fhir+json
Prefer: respond-async

{
    "resourceType": "Parameters",
    "parameter": [ {
            "name": "source-patient-identifier",
            "valueIdentifier": {
                    "system" : "urn:oid:1.2.36.146.595.217.0.1",
                    "value" : "12345"
            }
        },
        {
            "name": "target-patient-identifier",
            "valueIdentifier": {
                    "system" : "urn:oid:1.2.36.146.595.217.0.1",
                    "value" : "12346"
            }
        }
    ]
}

Output:

HTTP/1.1 202 Accepted

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "input",
      "resource": {
        "resourceType": "Parameters",
        ...copy of input...
      }
    },
    {
      "name": "task",
      "resource": {
        "resourceType": "Task",
        "id": "352",
        "identifier": [
          {
            "system": "http://hapifhir.io/batch/jobId",
            "value": "26738f4d-266c-4ef6-934f-1d13b1b474b9"
          }
        ],
        "status": "in-progress"
      }
    }
  ]
}

You can poll the status of the returned Task resource to see when it completes. For more detailed status about the background job, you can view the status of the corresponding Smile CDR batch job either through the Web Admin Console, or through the Admin JSON API. The ID of the Smile CDR batch job is provided as an identifer on the returned Task.

Provenance

A merge in this mode records what it changed across several Provenance resources rather than a single one, grouped by the partition the change was made in and the kind of change. Each of them carries a provenance-group extension (http://hapifhir.io/fhir/StructureDefinition/provenance-group) whose value ties the group together:

• One main Provenance for the operation as a whole. Its extension value is the bare group id, of the form merge|<source resource type>|<source id>|<target id>|<uuid>. It references the source and target Patients, contains the original input parameters of the operation, and does not list the individual changed resources.
• One member Provenance for each combination of partition and change type that occurred. Its extension value is the group id qualified with both, for example merge|Patient|123|456|<uuid>;partition=0;changeType=update. The change types are create, update and delete, corresponding to the copies created in the target Patient's compartment, the resources whose references were rewritten, and the originals that were deleted. Each member lists the resources it accounts for in Provenance.target, in addition to the source and target Patients of the merge.

Current Limitations

Scope

The operation is available as a resource-level operation at {resourceType}/$hapi.fhir.merge for any FHIR resource type, not just Patient resources. For example:

• Practitioner/$hapi.fhir.merge
• Organization/$hapi.fhir.merge

Parameter Names

The operation uses generic parameter names instead of Patient-specific ones:

• source-resource and target-resource (instead of source-patient and target-patient)
• source-resource-identifier and target-resource-identifier (instead of source-patient-identifier and target-patient-identifier)
• result-resource (instead of result-patient)

Resource Linking

The way merge relationships are tracked differs based on resource type:

• Patient resources: Continue to use the native Patient.link field to track merge relationships (with type of replaces and replaced-by)

• Non-Patient resources: Use FHIR extensions to track merge relationships:

  • The target resource receives an extension with URL http://hl7.org/fhir/StructureDefinition/replaces pointing to the source resource
  • The source resource receives an extension with URL http://hl7.org/fhir/StructureDefinition/replaced-by pointing to the target resource

  Example extension structure on target resource:

  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/replaces",
      "valueReference": {
        "reference": "Practitioner/100"
      }
    }
  ]
  

Provenance Activity Reason Codes

The operation automatically selects the appropriate FHIR activity reason code for the Provenance resource generated after the operation:

• PATADMIN - Used for Patient resource merges
• RECORDMGT - Used for all other resource type merges

Merge Example: Merge Practitioner/100 into Practitioner/200 synchronously

This example demonstrates merging two Practitioner resources. The operation uses the generic parameter names and creates extensions to track the merge relationship.

Input:

POST /Practitioner/$hapi.fhir.merge
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source-resource",
      "valueReference": {
        "reference": "Practitioner/100"
      }
    },
    {
      "name": "target-resource",
      "valueReference": {
        "reference": "Practitioner/200"
      }
    }
  ]
}

Output:

HTTP/1.1 200 OK

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "input",
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          {
            "name": "source-resource",
            "valueReference": {
              "reference": "Practitioner/100"
            }
          },
          {
            "name": "target-resource",
            "valueReference": {
              "reference": "Practitioner/200"
            }
          }
        ]
      }
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "details": {
              "text": "Merge operation completed successfully."
            }
          }
        ]
      }
    },
    {
      "name": "result",
      "resource": {
        "resourceType": "Practitioner",
        "id": "200",
        "extension": [
          {
            "url": "http://hl7.org/fhir/StructureDefinition/replaces",
            "valueReference": {
              "reference": "Practitioner/100"
            }
          }
        ],
        "identifier": [
          {
            "system": "http://example.org/practitioner-ids",
            "value": "PRAC200"
          },
          {
            "use": "old",
            "system": "http://example.org/practitioner-ids",
            "value": "PRAC100"
          }
        ],
        "name": [
          {
            "family": "Smith",
            "given": ["John"]
          }
        ]
      }
    }
  ]
}

Note that the merged Practitioner resource (Practitioner/200) includes:

• An extension with URL http://hl7.org/fhir/StructureDefinition/replaces pointing to the source resource (Practitioner/100)
• The identifiers from both the source and target resources, with the source identifiers marked with use: "old"
• The merged content based on the merge rules

Example: Undo merge of Practitioner/100 into Practitioner/200

Assuming that the $hapi.fhir.merge operation was previously performed to merge Practitioner/100 into Practitioner/200, you can undo that operation by calling $hapi.fhir.undo-merge with the same source and target parameters:

Input:

POST /Practitioner/$hapi.fhir.undo-merge
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source-resource",
      "valueReference": {
        "reference": "Practitioner/100"
      }
    },
    {
      "name": "target-resource",
      "valueReference": {
        "reference": "Practitioner/200"
      }
    }
  ]
}

Output:

HTTP/1.1 200 OK

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "details": {
              "text": "Successfully restored 8 resources to their previous versions based on the Provenance resource: Provenance/1475/_history/1"
            }
          }
        ]
      }
    }
  ]
}

Example: Undo merge of Patient/2 into Patient/3 (using Patient-specific parameter names)

For Patient resources merged via Patient/$merge, you can use the Patient-specific parameter names for backward compatibility:

Input:

POST /Patient/$hapi.fhir.undo-merge
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source-patient",
      "valueReference": {
        "reference": "Patient/2"
      }
    },
    {
      "name": "target-patient",
      "valueReference": {
        "reference": "Patient/3"
      }
    }
  ]
}

Output:

HTTP/1.1 200 OK

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "details": {
              "text": "Successfully restored 5 resources to their previous versions based on the Provenance resource: Provenance/2341/_history/1"
            }
          }
        ]
      }
    }
  ]
}

Limitations When Using Source Identifiers

When calling $hapi.fhir.undo-merge with source identifiers (instead of source resource reference), the following additional limitations apply:

• Source identifier-based undo only works if the original merge also used source identifiers. The merge operation stores its input parameters as part of the Provenance resource it creates. When source identifiers are used in undo-merge, the undo-merge operation locates the correct Provenance resource by matching these stored input parameters. Use source-resource-identifier in undo-merge only if the merge operation was called with source-resource-identifier. In other words, if the original merge was called with a source reference (e.g., source-resource: Practitioner/123), then the undo-merge must also be called with a source reference rather than source identifiers.

• All source identifiers provided to undo-merge must have been provided to the original merge. The matching logic requires that every source identifier provided to undo-merge exists in the Provenance's stored parameters. Providing a subset of the original source identifiers is allowed, but providing additional identifiers that were not part of the original merge will cause the operation to fail.

Best Practice: Either use the same source parameters as the original merge operation, or use source reference which always works.

Replace References Example: Replace all references to Patient/2 with references to Patient/3 synchronously.

Input:

POST /$hapi.fhir.replace-references
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source-reference-id",
      "valueString": "Patient/2"
    },
    {
      "name": "target-reference-id",
      "valueString": "Patient/3"
    }
  ]
}

Output:

HTTP/1.1 200 OK

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "outcome",
      "resource": {
        "resourceType": "Bundle",
        "id": "782add05-549c-4a7e-a687-38c22f2f12d0",
        "type": "transaction-response",
        "entry": [
          {
            "response": {
              "status": "200 OK",
              "location": "CarePlan/62/_history/2",
              "etag": "2",
              "outcome": {
                "resourceType": "OperationOutcome",
                "issue": [
                  {
                    "severity": "information",
                    "code": "informational",
                    "details": {
                      "coding": [
                        {
                          "system": "https://hapifhir.io/fhir/CodeSystem/hapi-fhir-storage-response-code",
                          "code": "SUCCESSFUL_PATCH",
                          "display": "Patch succeeded."
                        }
                      ]
                    },
                    "diagnostics": "Successfully patched resource \"CarePlan/62/_history/2\"."
                  }
                ]
              }
            }
          },
          ... etc outcome of the rest of the patch operations ...
        ]
      }
    }
  }
}

Example: Start a deduplication job

Submit one or more search URLs identifying the resources to deduplicate.

Input:

POST /$sdh.mdm-deduplicate
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "url",
      "valueString": "Patient?identifier=http://acme.org/mrn|12345"
    },
    {
      "name": "preview",
      "valueBoolean": false
    }
  ]
}

Output:

HTTP/1.1 202 Accepted
Content-Location: http://localhost:8000/$sdh.mdm-deduplicate.poll-for-status?_jobId=26738f4d-266c-4ef6-934f-1d13b1b474b9

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "$sdh.mdm-deduplicate job has been accepted. Poll for status at the following URL: http://localhost:8000/$sdh.mdm-deduplicate.poll-for-status?_jobId=26738f4d-266c-4ef6-934f-1d13b1b474b9"
    }
  ]
}

The Content-Location header (and the message in the returned OperationOutcome) contains the URL to poll for job status.

$sdh.mdm-deduplicate.poll-for-status Input Parameters

Example: Poll a job that is still running

Input:

GET /$sdh.mdm-deduplicate.poll-for-status?_jobId=26738f4d-266c-4ef6-934f-1d13b1b474b9

Output:

HTTP/1.1 202 Accepted
X-Progress: $sdh.mdm-deduplicate job has started and is in progress Current step: find-matches. Overall progress: 40%.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "$sdh.mdm-deduplicate job has started and is in progress Current step: find-matches. Overall progress: 40%."
    }
  ]
}

While the job is queued, in progress, or being finalized, the poll returns 202 Accepted. Keep polling until you receive 200 OK.

Example: Poll a completed job

When the job has completed, the poll returns 200 OK with a batch-response Bundle. The deduplication report is returned as the text of the contained OperationOutcome issue, summarizing how many pairs were merged (successTotal), skipped (skippedTotal), and failed (errorTotal), along with per-pair details.

Output:

HTTP/1.1 200 OK

{
  "resourceType": "Bundle",
  "type": "batch-response",
  "entry": [
    {
      "response": {
        "status": "200 OK",
        "outcome": {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "information",
              "code": "informational",
              "diagnostics": "{\"successTotal\":1,\"skippedTotal\":2,\"errorTotal\":0,\"results\":[{\"mergePair\":{\"targetId\":\"Patient/3\",\"sourceId\":\"Patient/2\",\"resourceType\":\"Patient\",\"exactMatch\":true},\"outcome\":\"SUCCESS\",\"message\":\"Successfully merged Patient/2 (source) into Patient/3 (target); preview=false.\"},{\"mergePair\":{\"targetId\":\"Patient/7\",\"sourceId\":\"Patient/6\",\"resourceType\":\"Patient\",\"exactMatch\":false},\"outcome\":\"SKIPPED\",\"message\":\"Possible MDM match: Patient/6 is a possible duplicate of Patient/7; surfacing for human review\",\"skipReason\":\"POSSIBLE_MATCH\"},{\"mergePair\":{\"targetId\":\"Patient/9\",\"resourceType\":\"Patient\",\"exactMatch\":true,\"skipReason\":\"TOO_MANY_CANDIDATES\"},\"outcome\":\"SKIPPED\",\"message\":\"Skipping merge for Patient/9 because too many match candidates were found; no merge source was selected.\",\"skipReason\":\"TOO_MANY_CANDIDATES\"}]}"
            }
          ]
        }
      }
    }
  ]
}

The report is a JSON document with the following fields:

When the outcome is SKIPPED, the skipReason field classifies why, so that consumers can act on the category without parsing the message text. It is absent for SUCCESS and ERROR results.