Skip to main content

Patient Match Operation

Overview​

The Patient Match operation provides MPI-based patient matching using comprehensive patient data rather than discrete search parameters. This operation enables healthcare systems to identify potential patient duplicates and matches using sophisticated matching algorithms.

Experimental

This is an experimental operation that is not yet supported by any Netsmart CareRecord or other solution.

Before implementing, validate operation availability in the CapabilityStatement:

GET {base-url}/metadata

Check the Patient resource operation elements for $match support.

Operation Schema​

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

Purpose: Find potential patient matches using MPI logic

Based on: HL7 FHIR R4 Patient Match Operation

Unlike Patient Search operations that use discrete parameters, Patient Match submits complete patient resources for comprehensive matching analysis.

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.[read|*]
  • v2: [patient|user|system]/Patient.[s] (future)

Parameters​

UseNameCardinalityTypeDocumentation
INresource1..1ResourceUse this to provide an entire set of patient details for the MPI to match against (e.g. POST a patient record to Patient/$match).
INonlyCertainMatches0..1booleanIf there are multiple potential matches, then the match should not return the results with this flag set to true. When false, the server may return multiple results with each result graded accordingly.
INcount0..1integerThe maximum number of records to return. If no value is provided, the server decides how many matches to return. Note that clients should be careful when using this, as it may prevent probable - and valid - matches from being returned.
OUTreturn1..1BundleA bundle contain a set of Patient records that represent possible matches, optionally it may also contain an OperationOutcome with further information about the search results (such as warnings or information messages, such as a count of records that were close but eliminated) If the operation was unsuccessful, then an OperationOutcome may be returned along with a BadRequest status Code (e.g. security issue, or insufficient properties in patient fragment - check against profile)

Examples​

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

Payloads​

Sample Match Request Payload​

{
  "resourceType": "Parameters",
  "id": "example",
  "parameter": [
    {
      "name": "resource",
      "resource": {
        // A valid Patient resource
      }
    },
    {
      "name": "count",
      "valueInteger": "50"
    },
    {
      "name": "onlyCertainMatches",
      "valueBoolean": "false"
    }
  ]
}

Sample Match Response Payload​

{
  "resourceType": "Bundle",
  "id": "bfef1cc5-9204-465b-b910-a3d59430b97f",
  "type": "searchset",
  "total": 11,
  "entry": [
    {
      "fullUrl": "https://.../Patient/1",
      "resource": {
        // A matching Patient resource
      },
      "search": {
        "extension": [{
          "url": "http://hl7.org/fhir/StructureDefinition/match-grade",
          "valueCode": "certain"
        }],
        "mode": "match",
        "score": 0.9
      }
    },
    // Additional matches excluded for brevity
  ]
}

Integration Patterns​

Match Workflow​

  1. Prepare Patient Resource

    • Include comprehensive demographic data
    • Provide identifiers, names, addresses
    • Add contact information when available

  2. Submit Match Request

    • POST Parameters resource with patient data
    • Include matching preferences (onlyCertainMatches, count)
    • Handle authentication and authorization

  3. Process Match Results

    • Review returned Bundle with potential matches
    • Evaluate match scores and grades
    • Handle OperationOutcome messages

Best Practices​

  • Provide as much patient data as possible for accurate matching
  • Use standardized identifiers (SSN, MRN, etc.)
  • Consider match scores when evaluating results
  • Implement appropriate thresholds for match acceptance

Match Quality Assessment​

  • Certain matches: High confidence, likely same patient
  • Probable matches: Good confidence, requires review
  • Possible matches: Lower confidence, manual verification needed

Relationships to Other Resources​

  • Patient Resource - Primary resource for matching
  • Patient Search - Alternative search approach
  • Parameters Resource - Operation input format
  • Bundle Resource - Match results container

Error Handling​

For comprehensive error handling information, see Common Errors.

Support​

For technical support with Patient Match operations: