Payer Services PDex $member-match API Specification
Service Overview
InterSystems Payer Services PDex APIs support the sharing of patient health data and are designed in compliance with the CMS-0057-F regulationsOpens in a new tab. The APIs allow patients to access the health information held by their payer, providers to access clinical data for patients they have a relationship with, and payers to access health data for their members who have multiple or prior health plans.
The $member-match API allows providers to identify a single patient using demographic and coverage information and obtain the patient's unique member identifier when a match is found and consent permits data sharing. Bulk member match requsts can be made using the $provider-member-match API.
Refer to the Getting Started section for information on connectivity, authentication and how to get help. To use the REST APIs, you will need to know the server URL of the FHIR server you will be connecting to.
Workflow
A typical workflow involving the $member-match operation used in a Provider Access scenario might be:
-
The provider uses the $member-match operation to request the unique member FHIR identifier for their patient from the patient's payer.
-
The payer returns the member's member FHIR identifier to the provider.
-
Using the returned FHIR identifier, the provider can then invoke the $everything operation to retrieve the patient's data from the payer.
Endpoint: $member-match
Base URL
The base URL of the $member-match operation is:
<server url>/csp/healthshare/<namespace>/app/api/responder/FHIRResponderService
where <server url> and <namespace> have been given to you by the payer organization you are connecting with.
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 patient being searched for must exist in the member identity system of the payer being queried.
-
The provider must have an attributed treatment relationship with the patient.
-
The patient being matched cannot previously have opted out of this service.
Required Header Settings
-
Content-Type: application/fhir+json
-
Accept: application/fhir+json
Request Methods
Invokes the member match operation.
Query Parameters
None.
Request Body
The request body of a $member-match request must conform with the format specified in the HRex Implementation GuideOpens in a new tab.
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 in the CoverageToMatch section:
{
"resourceType": "Parameters",
"id": "member-match-in-provider",
"parameter": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"id": "1",
"name": [
{
"use": "official",
"family": "Person",
"given": [
"Patricia",
"Ann"
]
}
],
"gender": "female",
"birthDate": "1974-12-25"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"id": "9876B1",
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MB"
}
]
},
"system": "http://example.org/old-payer",
"value": "TestMB"
}
]
}
}
]
}
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"] }
],
"gender": "female",
"birthDate" : "1974-01-01"
}
}
]
}
The following shows sample request body content with demographic information containing multiple names and one address; it also includes birthsex rather than gender:
{
"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": "11201"
}
],
"birthDate" : "1974-01-01"
"extension": [
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
"valueCode": "F"
}
]
}
}
]
}
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"}
],
"gender" : "male",
"birthDate" : "1975-01-01"
}
},
{
"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:
{
"resourceType": "Parameters",
"id": "member-match-out",
"parameter": [
{
"name": "MemberIdentifier",
"valueIdentifier": {
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MB"
}
]
},
"value": "TESTMB"
}
},
{
"name": "MemberId",
"valueReference": {
"reference": "<server>/pdex/csp/healthshare/pdex/app/api/responder/FHIRResponderService/Patient/100000038"
}
}
]
}
where “TESTMB” is the value of the member identifier (their card number) with an identifier type of “MB” and 100000038 is the MPI ID that references the Patient resource.
Error Responses
The following response error codes are possible when using the member match operation:
Possible causes include:
-
No valid token found
The requester does not have the necessary permissions, accompanied by an OperationOutcomeOpens in a new tab resource that indicates the specific nature of the failure. This could include:
-
The requester type from the JWT is not “provider”
-
Token does not include required OAuth scopes
Possible causes include:
-
Accept header does not include application/fhir+json.
Possible causes include:
-
Content-Type header is not application/fhir+json.
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, such as missing required fields from the Patient resource
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
Possible causes include:
-
An internal request in the process timed out