The patient matching functionality enables payers to accurately identify and match member records between systems during Payer-to-Payer data exchanges. This includes both single-member matching via $member-match and multi-member matching via $bulk-member-match operations.

Default Matching Logic

By default, Smile executes very simple matching logic not suitable for production. It is simply intended to support testing of the operation.

Presently, only family name and birthdate from the MemberPatient parameter are used as matching criteria. The operation will return a success response only if there is one match against a Patient resource.

$member-match: Single Member Match

Smile CDR supports the $member-match operation as defined in the HRex implementation guide.

The $member-match operation is a component of single record exchange and a required precursor to any subsequent record request via $export. It enables a requesting payer to submit member demographic and coverage information for one member to a source payer to identify matching members within their system. A successful operation returns record identifiers for matched members that can be used to request an access token and export data.

Response Behavior

Smile CDR will return both:

The required MemberIdentifier (UMB business identifier)
The optional MemberId reference to the Patient record

Other response behavior follows the IG:

A maximum of one (1) unique match will be returned
In the case of no matches, a 422 error will be returned.
In case of more than one unique resource matching, a 422 error will be returned.
If consent is provided, inability to comply with consent requirements SHALL return a 422 status code

$bulk-member-match: Multi-Member Match

Smile CDR supports the $bulk-member-match operation as defined in version 2.1.0 - STU1 of the Da Vinci Payer-to-Payer Data Exchange Implementation Guide (PDex IG).

The $bulk-member-match operation is a crucial component of multi-member record exchange and a required precursor to any subsequent record request via $davinci-data-export. It enables a requesting payer to submit a batch of member demographic and coverage information to a source payer to identify matching members within their system.

Response Groups

The $bulk-member-match operation will return potentially three groups:

Matched members - Members successfully identified in the system
Non-matched members - Members not found in the system
Consent-restricted members - Members who matched but have consent policies that cannot be satisfied

OperationOutcome Details

For non-matched and consent-restricted members, the response Groups include OperationOutcome resources as contained resources that provide diagnostic information about why the match failed

In the matched-members Group, a member whose matched Patient has no local resource id (for example, a member matched at an external plan by a custom match function) is represented as a contained Patient, preserved verbatim, with the group member entity referencing it via a fragment reference. The contained resource id is deterministic but opaque; consumers must not rely on any particular format or prefix.

Customizing Matching Logic

To make the $member-match operation adapt to business requirements unique to each customer, the System-to-System Data Exchange Module supports custom matching scripts that can be defined by clients in the form of JavaScript.

Custom Script Template

The Module selects the script function based on the operation. Define payerMatchPatient for the payer-initiated $member-match and $bulk-member-match operations. Each function takes two parameters: the first exposes the memberPatient, coverageToMatch, and (when supplied) consent from the request, and the second contains details about the request that is about to be processed:

function payerMatchPatient(theMemberMatchRequest, theRequestDetails) {
    // your implementation goes here
}

The function will return:

Patient if a matching patient is found
null if not found

Note: If null is returned, then the system will throw a 422 Unprocessable entity stating that the matching Patient is not found.

See Custom Matching Script for the full reference, including the provider-initiated providerMatchAndValidateRelationship function and the deprecated legacy matchPatient function.

Configuration for Matching

Patient Identifier Configuration

When configuring the System to System Data Exchange Module:

Configuration Item	Description	Example
Reference System used by Target Patient	Defines the FHIR `Patient.identifier.system` that Smile CDR will use to identify patients within your own local system	`http://yourhealthplan.example.com/patient-id`
Responder Identifier System	System for the Identifier used to store the original IDs of imported resources from the Responder (Source) server	`http://sourcehealthplan.example.com/member-id`

Consent Filtering Configuration

Configuration Item	Description	Impact
Support Consent Filtering on $member-match requests	Enable/disable consent policy application	If enabled, all configured regular consent policies apply. If disabled, only #sensitive policies are considered

Implementation Considerations

Key Questions for Responding Payers

When implementing matching logic as a responding payer, consider:

What matching rules will we implement for identifying the correct member record to share?
How will we handle multiple potential matches?
What level of confidence is required for a successful match?
How will we handle partial matches or ambiguous results?

Business Identifier Management

For multi-member matching with $bulk-member-match, it is essential to associate the group with a unique business identifier. This identifier allows Smile CDR to enforce fine-grained access control, ensuring that a client system can only access the data for which it has explicit permissions.

Solution Modules & Standards Data Exchange Patterns