PDex Member Match $member-match FHIR API Specification
Service Overview
InterSystems PDex Member Match (Member Match) FHIR APIs are designed in compliance with the CMS-0057-F regulationsOpens in a new tab.
Refer to the Getting Started section for information on connectivity, authentication and how to get help. To use the FHIR APIs, you will need to know the base URL of the FHIR server you will be connecting to. You can also retrieve the capability statement for the service.
This API allows a consumer, who may be a provider or payer, to get a patient’s or member’s unique identifier from another payer. The identifying information needed to ensure accurate matching may depend on the member identity system your patient/member’s payer is using.
Workflow
The Member Match FHIR API is used to retrieve a member’s unique identifier from a payer’s system. A typical workflow involving the member match operation (with simplified authorization steps) might be:
-
A member gives permission to the payer organization of their new plan to gather their data, providing information about their previous coverage.
-
The new payer organization determines the endpoint for the previous plan.
-
The new payer organization requests access credentials to the previous plan’s API.
-
The new payer organization calls the member match API to get the member’s unique identifier.
-
If a unique identifier is found, the previous payer organization returns an access token to permit data for the member the plans have in common to be retrieved.
Prerequisites
None
Endpoint: $member-match
URL
The member match URL is:
<BaseURL>/Patient/$member-match
Optional Capabilities
None.
Endpoint Prerequisites
In order to use the member match operation, the following must be satisfied:
-
The member match endpoint information must be known.
To successfully find a matching member identifier:
-
The member being searched for must exist in the member identity system of the payer being queried.
-
The member being matched cannot previously have opted out of this service.
Required Header Settings
-
Content-Type: application/json+fhir
-
Accept: application/json+fhir
Request Methods
Invokes the member match operation.
This method should be called asynchronously as it is performing a lookup on a member identity system, which may take an indeterminate amount of time to respond.
Query Parameters
None.
Request Body
The member match operation supports lookup in a number of ways. The most common lookups use at least one of the following in the request body:
The member match operation also requires valid consent information to be included in the request body. A sample of consent payload is as follows:
{
"resourceType": "Parameters",
"id": "member-match-in",
"parameter": [
{
"name": "Consent",
"resource": {
"resourceType": "Consent",
"status": "active",
"scope": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentscope",
"code": "patient-privacy"
}
]
},
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IDSCL"
}
]
}
],
"patient": {
"reference": "Patient/1"
},
"performer": [
{
"reference": "Patient/1"
}
],
"sourceReference": {
"reference": "http://example.org/DocumentReference/someconsent.pdf"
},
"policy": [
{
"uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#regular"
}
],
"provision": {
"type": "permit",
"period": {
"start": "2022-01-01",
"end": "2022-01-31"
},
"actor": [
{
"role": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
"code": "performer"
}
]
},
"reference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "9876543210"
},
"display": "Old Health Plan"
}
},
{
"role": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "IRCP"
}
]
},
"reference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "0123456789"
},
"display": "New Health Plan"
}
}
],
"action": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentaction",
"code": "disclose"
}
]
}
]
}
}
}
]
}
Member Number
The following shows sample request body content with a member number and MB as the identifier type code:
{
"resourceType" : "Parameters",
id" : "member-match-in-provider",
"parameter" : [
{
"name" : "MemberPatient",
"resource" : {
"resourceType" : "Patient",
"id" : "1",
"identifier" : [
{
"type" : {
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "MB"
}
]
},
"system" : "http://example.org/target-payer/identifiers/member",
"value" : "TESTMB1"
}
]
}
}
]
}
A search with a member number can generally be expected to return a match without additional demographic information in the request body.
Demographics
A demographic search supports the possible use of multiple names and/or multiple addresses. The following shows sample request body content with demographic information with multiple names:
{
"resourceType": "Parameters",
"id": "member-match-in-provider",
"parameter": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"id": "1",
"name": [
{ "use": "official", "family": "McDonald", "given": ["Christine"] },
{ "use": "official", "family": "Fits", "given": ["Christine"] }
]
}
}
]
}
The following shows sample request body content with demographic information containing multiple names and one address:
{
"resourceType": "Parameters",
"id": "member-match-in-provider",
"parameter": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"id": "1",
"name": [
{ "use": "official", "family": "McDonald", "given": ["Christine"] },
{ "use": "official", "family": "Fits", "given": ["Christine"] }
],
"address": [
{
"line": ["2300 King Road", "Apt 34"],
"city": "Brooklyn",
"state": "NY",
"postalCode": "78754"
}
]
}
}
]
}
Subscriber Number
The following shows sample request body content with a subscriber number as the subscriberId:
{
"resourceType": "Parameters",
"id": "member-match-in-provider",
"parameter": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"id": "1",
"name": [
{"use": "official", "given": ["Richard"], "family": "Knight"}
]
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"id": "9876B1",
"subscriberId": "TESTSN"
}
}
]
{
A search with subscriber information typically requires additional demographics in the request body to return a match since a family may share a single subscriber ID, and it is not a unique identifier.
Success Response
The request succeeded. A unique member identifier was found for the member. Example body content:
{
"mpiid":"100000084",
}
where mpiid is an indicator of the type of the identifier and 100000084 is the member identifier found in the FHIR repository.
Error Responses
The following response error codes are possible when using the member match operation:
Error calling the member match service, accompanied by an OperationOutcomeOpens in a new tab resource that indicates the specific nature of the failure. This could include:
-
No match found
-
Multiple matches found
-
Member consent not given
-
Bad bundle format
Error from payer’s person identity or consent service, accompanied by an OperationOutcomeOpens in a new tab resource that indicates the specific nature of the failure. This could include:
-
Request was missing data required by the person identity service
-
Request was missing data required by the consent service
-
Payer’s system has missing configuration information
Possible causes and return messages include:
-
The member match endpoint is not properly set, or does not return a response, the error includes a no-store message
-
An unregistered operation or resource is requested, the error message includes The handler for operation '[operation]' for resource type '[resource type]/[resource id]' is not registered