Patient Match Operation

Experimental

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

OPERATION: POST [base]/Patient/$match

The Patient Match operation provides an alternative searching using MPI based logic and is based on the HL7 FHIR R4 Patient Match Operation specification. Unlike the Patient Search operation which uses discrete search parameters, with Patient Match the application submits an entire patient resource for matching based on the MPI's matching logic.

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

Use	Name	Cardinality	Type	Documentation
IN	resource	1..1	Resource	Use this to provide an entire set of patient details for the MPI to match against (e.g. POST a patient record to Patient/$match).
IN	onlyCertainMatches	0..1	boolean	If 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.
IN	count	0..1	integer	The 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.
OUT	return	1..1	Bundle	A 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

Production

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

Preview

curl -X POST 'https://fhirtest.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
  ]
}

Errors

To be written.