Payer Services PDex $bulk-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 $bulk-member-match API allows payers to identify multiple patients using demographic and coverage information and obtain the patient's unique member identifier when a match is found and consent permits data sharing.
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 $bulk-member-match operation used in a Payer Access scenario might be:
-
Members enroll in the requesting payer's system.
-
The requesting payer generates a batch of these members.
-
The requesting payer uses the $bulk-member-match operation to submit the batch to the previous payer and generate a Group of matched members.
-
The requesting payer uses the status method to poll for updates on the original member match request.
-
Once the member match request is complete, the requesting payer can download the NDJSON files containing the group data for matched, non-matched, and consent constrained members.
-
The requesting payer uses the returned Group ID information for matched members to invoke the $davinci-data-export operation to retrieve the members' data from their previous payer.
Endpoint: $bulk-member-match
Base URL
The base URL of the $bulk-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 $bulk-member-match operation, the following must be satisfied:
-
The endpoint information must be known.
To successfully find a matching member's identifier:
-
The member being searched for must exist in the member identity system of the payer being queried.
-
The member being matched must be opted in to share data with the requesting payer.
Required Header Settings
-
Content-Type: application/fhir+json
-
Accept: application/fhir+json
-
Prefer: respond-async (for the initial bulk member match request)
Request Methods
Invokes the bulk member match operation.
where <sessionId > is the session identifier for the bulk member match you initiated.
You can use this to poll for the status of a bulk member match request.
where <sessionId > is the session identifier for the bulk member match you initiated and <fileName> identifies the NDJSON file you want to download.
You can use this to download the NDJSON files created for the bulk member match request.
Request Body
Initial Bulk Request Body
A bulk member match request is formatted as a FHIR Parameters resource with a repeating list of parameters that each represent one member (Patient resource). Each MemberBundle entry in the bulk member match request must conform with the guidelines provided for a single $member-match request body.
Sample request body:
{
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberBundle",
"part": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"id": "1",
"identifier": [
{
"system": "http://oldpayer.example.com/member",
"value": "55678"
}
],
"name": [
{
"family": "Doe",
"given": [
"Jane"
]
}
],
"gender": "female",
"birthDate": "1970-05-01"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"id": "cov-match-1",
"status": "active",
"identifier": [
{
"system": "http://oldpayer.example.com/policy",
"value": "AA87654"
}
],
"beneficiary": {
"reference": "Patient/1"
},
"payor": [
{
"identifier": {
"value": "OldPayer"
}
}
]
}
},
{
"name": "CoverageToLink",
"resource": {
"resourceType": "Coverage",
"id": "cov-link-1",
"status": "active",
"identifier": [
{
"system": "http://newpayer.example.com/policy",
"value": "23847239"
}
],
"beneficiary": {
"reference": "Patient/1"
},
"payor": [
{
"identifier": {
"value": "NewPayer"
}
}
]
}
},
{
"name": "Consent",
"resource": {
"resourceType": "Consent",
"id": "consent-1",
"status": "active",
"scope": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentscope",
"code": "patient-privacy"
}
]
},
"category": [
{
"coding": [
{
"system": "http://loinc.org",
"code": "64292-6"
}
]
}
],
"patient": {
"reference": "Patient/1"
},
"policyRule": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentpolicycodes",
"code": "hipaa-auth"
}
]
}
}
}
]
},
{
"name": "MemberBundle",
"part": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"id": "2",
"identifier": [
{
"system": "http://oldpayer.example.com/member",
"value": "99001"
}
],
"name": [
{
"family": "Smith",
"given": [
"John"
]
}
],
"gender": "male",
"birthDate": "1985-11-23"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"id": "cov-match-2",
"status": "active",
"identifier": [
{
"system": "http://oldpayer.example.com/policy",
"value": "BB11223"
}
],
"beneficiary": {
"reference": "Patient/2"
},
"payor": [
{
"identifier": {
"value": "OldPayer"
}
}
]
}
},
{
"name": "Consent",
"resource": {
"resourceType": "Consent",
"id": "consent-2",
"status": "active",
"scope": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentscope",
"code": "patient-privacy"
}
]
},
"patient": {
"reference": "Patient/2"
},
"policyRule": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentpolicycodes",
"code": "hipaa-auth"
}
]
}
}
}
]
}
]
}
Bulk Member Match Status Request Body
None. Use the sessionId from the response to your initial bulk request as a path parameter to get the member match request status.
Bulk Member Match File Request Body
None. Use the sessionId and the fileName that was returned by the status response as path parameters to download the resource files.
Success Response
Initial Bulk Member Match Response
The request was accepted.
The response header includes a ContentLocation entry that gives the endpoint that can be used for subsequent status requests. The sessionId is given in the last part of the URL path.
Status of Bulk Member Match Response
The request succeeded. Processing of the bulk request is complete.
The response body contains an output array with one or more Group entries and associated Parameters entries that identify the type of Group (for example, matched members). Each has a url property that includes the name of the NDJSON file containing the data for that resource. A response for a bulk member match request might look something like this:
{
"transactionTime": "2026-08-13T13:28:11Z",
"request": "<server>/csp/healthshare/hp-pdex/app/api/responder/FHIRResponderService/Group/$bulk-member-match",
"output": [
{
"type": "Group",
"url": "<server>/csp/healthshare/hp-pdex/app/api/responder/FHIRResponderService/bulk-data-export/file/21/Group_Group-0001.ndjson"
},
{
"type": "Parameters",
"url": "<server>/csp/healthshare/hp-pdex/app/api/responder/FHIRResponderService/bulk-data-export/file/21/Parameters_Parameters-0001.ndjson"
}
],
"error": [],
"requiresAccessToken": "true"
}
The request was accepted.
This code indicates the bulk member match session is still in progress. The response contains a RETRY-AFTER header with an integer in seconds. This indicates how long a requester must wait before making another status polling request
Bulk Member Match File Response
The request was successful.
The NDJSON file content is included in the response body.
Error Responses
The following response error codes may be returned, depending on the method invoked:
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:
-
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.
Possible causes include:
-
The requester has polled the status endpoint too frequently
Error from the responding payer's internal systems, accompanied by an OperationOutcomeOpens in a new tab resource that indicates the specific nature of the failure. This could include:
-
Request was missing required data
-
Payer's system has missing configuration information
-
The session does not belong to the requester
Possible causes include:
-
An internal request in the process timed out