Skip to main content

Patient Merge Operation

Overview​

The Patient Merge operation consolidates duplicate patient records by merging a source patient into a target patient. This operation helps maintain data integrity and provides a unified view of patient information across healthcare systems.

info

Not all Netsmart solutions support Patient merge via CareConnect. Validate support in the CapabilityStatement before implementation.

Before implementing, validate operation availability in the CapabilityStatement:

GET {base-url}/metadata

Check Patient resource operation elements for $merge support.

Operation Schema​

Endpoint: POST {base-url}/Patient/$merge

Purpose: Merge duplicate patient records

Based on: Draft HL7 FHIR Patient Merge Operation

Authorization​

This operation will require the application obtain authorization to update a Patient using one of the following SMART clinical scopes.

  • v1: [patient|user|system]/Patient.[write|*]
  • v2: [patient|user|system]/Patient.[u] (future)

Parameters​

UseNameCardinalityTypeDocumentation
INsource-patient1..1ReferenceA direct resource reference to the source patient resource.
INtarget-patient1..1ReferenceA direct resource reference to the target patient resource.
This is the surviving patient resource, the target for the merge.
INpreview0..1booleanThis parameter is not yet supported by any Netsmart CareRecord or solution
If this is set to true then the merge will not be actually performed; an OperationOutcome will be returned in the Parameters response that will indicate that no merge has occurred and may include other diagnostic info if desired, such as the scale of the merge.
e.g. Issue.details.text "Preview only Patient merge - no issues detected"
e.g. Issue.diagnostics "Merge would update: 10 years of content or 120 resources"
The resulting target patient resource will also be returned in the result.
OUToutcome1..1OperationOutcomeThe outcome of the operation. On success this will provide a success statement or warnings related to the change. If the operation was unsuccessful, the OperationOutcome will include the reason for the failure.

Examples​

curl -X POST 'https://fhir.netsmartcloud.com/v4/Patient/$merge' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d @payload.json

Payloads​

Sample Merge Request Payload​

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

Sample Merge Response Payload​

Merge Success​
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source-patient",
      "valueReference": {
        "reference": "Patient/1"
      }
    },
    {
      "name": "target-patient",
      "valueReference": {
         "reference": "Patient/2"
      }
    },
    {
      "name": "preview",
      "valueBoolean": false
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "code": "informational",
            "details": {
              "text": "Success message"
            }
          }
        ]
      }
    }
  ]
}
Invalid Merge Payload or Other Unprocessable Request​
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "processing",
      "details": {
        "text": "Exception message"
      }
    }
  ]
}
Rejections or Other Merge Processing Errors​
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "source-patient",
      "valueReference": {
        "reference": "Patient/1"
      }
    },
    {
      "name": "target-patient",
      "valueReference": {
         "reference": "Patient/2"
      }
    },
    {
      "name": "preview",
      "valueBoolean": false
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "error",
            "code": "processing",
            "details": {
              "text": "err: Target Patient not found"
            }
          }
        ]
      }
    }
  ]
}

Integration Patterns​

Merge Workflow​

  1. Identify Duplicate Patients

    • Use Patient Match operation or manual review
    • Determine source (duplicate) and target (surviving) patients
    • Validate patient relationships and dependencies

  2. Prepare Merge Request

    • Create Parameters resource with patient references
    • Consider using preview mode for validation
    • Include proper authorization

  3. Execute Merge

    • Submit merge operation
    • Process OperationOutcome response
    • Handle success or failure scenarios

  4. Post-Merge Validation

    • Verify target patient contains merged data
    • Confirm source patient is properly handled
    • Update external system references

Best Practices​

  • Always use preview mode first to validate merge feasibility
  • Backup critical data before performing merges
  • Document merge decisions and rationale
  • Test merge operations in non-production environments
  • Implement proper access controls for merge operations

Merge Considerations​

  • Data Consolidation: All clinical data from source patient moves to target
  • Identifier Management: Handle conflicting identifiers appropriately
  • Audit Trail: Maintain record of merge operations
  • Reversibility: Consider unmerge capabilities if available

Relationships to Other Resources​

Error Handling​

For comprehensive error handling information, see Common Errors.

Support​

For technical support with Patient Merge operations: