$bulk-member-match operation is used to get matches for a Group of Patient resources in a asynchronous manner. The operation starts a batch job and the returns a polling url.$member-match.The $bulk-member-match operation supports both asynchronous and synchronous processing. Include the Prefer: respond-async header for asynchronous execution; omit it for synchronous execution. The request body is a Parameters resource containing one or more MemberBundle parameter groups, each with a MemberPatient, CoverageToMatch, CoverageToLink, and optionally a Consent.
POST /Group/$bulk-member-match
Content-Type: application/fhir+json
Prefer: respond-async
{
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberBundle",
"part": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"identifier": [
{
"type": {
"coding": [
{
"system": "http://hl7.davinci.org",
"code": "MB"
}
]
},
"system": "http://sourcehealthplan.example.com",
"value": "55678"
}
],
"name": [
{
"use": "official",
"family": "Person",
"given": ["Patricia", "Ann"]
}
],
"gender": "female",
"birthDate": "1974-12-25"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"id": "SOURCE_COVERAGE_ID",
"identifier": [
{
"system": "http://sourcehealthplan.example.com",
"value": "SOURCE_IDENTIFIER"
}
],
"status": "draft",
"beneficiary": {
"reference": "BENEFICIARY_PATIENT_ID"
},
"payor": [
{
"reference": "Organization/2"
}
]
}
},
{
"name": "CoverageToLink",
"resource": {
"resourceType": "Coverage",
"id": "AA87654",
"identifier": [
{
"system": "http://targetealthplan.example.com",
"value": "234567"
}
],
"status": "active",
"beneficiary": {
"reference": "Patient/1"
},
"payor": [
{
"reference": "Organization/3"
}
]
}
},
{
"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"
}
}
}
]
}
]
}
Upon a successful kickoff, the server responds with HTTP 202 Accepted and a Content-Location header containing the polling URL.
HTTP/1.1 202 Accepted
Content-Location: https://example.com/fhir/Group/$bulk-member-match-poll-status?_jobId=abc-123
GET /Group/$bulk-member-match-poll-status?_jobId=abc-123
HTTP/1.1 202 Accepted
X-Progress: Build in progress - Status set to IN_PROGRESS
Retry-After: 120
HTTP/1.1 200 OK
Content-Type: application/json
{
"transactionTime": "2025-01-15T10:30:00.000+00:00",
"request": "https://example.com/fhir/Group/$bulk-member-match",
"requiresAccessToken": false,
"output": [
{
"type": "Binary",
"url": "https://example.com/fhir/Binary/abc-123"
}
],
"error": []
}
The output url points to a Binary resource containing the match results. The error array will contain entries if any errors occurred during processing. If the job fails entirely, the server responds with HTTP 500 and an OperationOutcome.
Example of the content with matched members:
{
"resourceType": "Parameters",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/pdex-parameters-multi-member-match-bundle-out"
]
},
"parameter": [
{
"name": "MatchedMembers",
"resource": {
"resourceType": "Group",
"id": "6709",
"meta": {
"versionId": "1",
"lastUpdated": "2025-12-05T10:52:01.349-05:00",
"profile": [
"http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/pdex-member-match-group"
]
},
"contained": [
{
"resourceType": "Patient",
"id": "M123",
"identifier": [
{
"type": {
"coding": [
{
"system": "http://hl7.davinci.org",
"code": "MB"
}
]
},
"system": "http://oldhealthplan.example.com",
"value": "55678",
"assigner": {
"reference": "Organization/org2"
}
},
{
"use": "usual",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MB",
"display": "Member Number",
"userSelected": false
}
],
"text": "Member Number"
},
"system": "urn:uri:payer-org-target:eid",
"value": "tgt-eid-value-100123"
}
],
"name": [
{
"use": "official",
"family": "Person",
"given": [
"Patricia",
"Ann"
]
}
],
"gender": "female",
"birthDate": "1974-12-25"
}
],
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "defaultS2sBusId"
}
],
"type": "person",
"actual": true,
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS",
"code": "match",
"display": "Matched"
}
]
},
"characteristic": [
{
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS",
"code": "match",
"display": "Matched"
}
]
},
"valueReference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "defaultS2sBusId"
}
},
"exclude": false,
"period": {
"start": "2025-12-05T10:52:01-05:00"
}
}
],
"member": [
{
"entity": {
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters",
"valueReference": {
"reference": "#M123"
}
}
],
"reference": "Patient/P123"
}
}
]
}
}
]
}
The $bulk-member-match operation also supports synchronous processing. To execute synchronously, omit the Prefer: respond-async header. The response will be returned directly as a Parameters resource containing matched, non-matched, and consent-constrained member Groups.
Synchronous processing must be explicitly enabled by setting the allow_synchronous_member_match configuration property to true on the System to System Data Exchange module. If this property is not enabled and the Prefer: respond-async header is omitted, the request will be rejected.
The $provider-member-match operation enables provider-initiated member matching. While $bulk-member-match is designed for payer-to-payer data exchange where a patient provides consent, $provider-member-match is used when a healthcare provider attests to treatment needs on behalf of the patient.
The key differences from $bulk-member-match are in the Consent resource within each MemberBundle:
| Field | $bulk-member-match (PDex Consent) | $provider-member-match (Treatment Attestation) |
|---|---|---|
scope.coding.code | patient-privacy | treatment |
performer | Patient reference (patient consenting) | Practitioner reference (provider attesting) |
All other aspects of the operation are identical: the same MemberPatient, CoverageToMatch, and CoverageToLink parameters, the same matching logic, and the same response format.
The caller needs these permissions:
FHIR_OP_MEMBER_MATCH to call the operation.FHIR_EXTENDED_OPERATION_ON_TYPE with argument Group/$provider-member-match-poll-status to poll an asynchronous request.FHIR_READ_ALL_OF_TYPE with argument Binary to read the asynchronous result.No Consent, Group, Patient or Coverage permissions are needed: Smile CDR stores the match Group and the treatment attestation Consents itself. The stored match Group carries each of the caller's business identifiers (the auth-business-identifiers session value, see Business Identifier Methods) in Group.identifier. Because every call stores a new Group, grant the provider FHIR_OP_INITIATE_BULK_DATA_EXPORT_GROUPS_MATCHING with a search on that identifier so that it can run $davinci-data-export on its Groups. See Grant Permissions to the Provider System.
Like $bulk-member-match, this operation supports both asynchronous and synchronous processing. Include the Prefer: respond-async header for asynchronous execution; omit it for synchronous execution.
POST /Group/$provider-member-match
Content-Type: application/fhir+json
Prefer: respond-async
{
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberBundle",
"part": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"identifier": [
{
"type": {
"coding": [
{
"system": "http://hl7.davinci.org",
"code": "MB"
}
]
},
"system": "http://sourcehealthplan.example.com",
"value": "55678"
}
],
"name": [
{
"use": "official",
"family": "Person",
"given": ["Patricia", "Ann"]
}
],
"gender": "female",
"birthDate": "1974-12-25"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"id": "SOURCE_COVERAGE_ID",
"identifier": [
{
"system": "http://sourcehealthplan.example.com",
"value": "SOURCE_IDENTIFIER"
}
],
"status": "draft",
"beneficiary": {
"reference": "BENEFICIARY_PATIENT_ID"
},
"payor": [
{
"reference": "Organization/2"
}
]
}
},
{
"name": "CoverageToLink",
"resource": {
"resourceType": "Coverage",
"id": "AA87654",
"identifier": [
{
"system": "http://targetealthplan.example.com",
"value": "234567"
}
],
"status": "active",
"beneficiary": {
"reference": "Patient/1"
},
"payor": [
{
"reference": "Organization/3"
}
]
}
},
{
"name": "Consent",
"resource": {
"resourceType": "Consent",
"status": "active",
"scope": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentscope",
"code": "treatment"
}
]
},
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IDSCL"
}
]
}
],
"patient": {
"reference": "Patient/1"
},
"performer": [
{
"reference": "Practitioner/1"
}
],
"policy": [
{
"uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#sensitive"
}
],
"provision": {
"type": "permit",
"period": {
"start": "2024-01-01",
"end": "2024-12-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": "Provider Organization"
}
},
{
"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": "Target Health Plan"
}
}
],
"action": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentaction",
"code": "disclose"
}
]
}
]
}
}
}
]
}
]
}
HTTP/1.1 202 Accepted
Content-Location: https://example.com/fhir/Group/$provider-member-match-poll-status?_jobId=abc-456
The polling mechanism and response format are identical to $bulk-member-match. Use the $provider-member-match-poll-status endpoint with the _jobId parameter:
GET /Group/$provider-member-match-poll-status?_jobId=abc-456
The completed response contains matched, non-matched, and consent-constrained member Groups in the same structure as described in the $bulk-member-match section above.