Payerbox Docs

Payer-to-Payer

Payer-to-Payer flow: Another payer calls Payerbox's $bulk-member-match to identify a member and pulls the matched member's history via $davinci-data-export; Payerbox returns data fed from the Health Plan's internal data sources. The receiving payer (not Payerbox) captures the member's opt-in consent during enrollment and submits it with the request.

The Payer-to-Payer API lets a receiving payer (new plan) pull a member's clinical, claims, encounter, and prior-authorization history from a previous payer when the member changes coverage. Established by CMS-0057-F, effective January 1, 2027. Replaces the suspended 9115 P2P provision.

What Payerbox covers

  • Asynchronous FHIR $bulk-member-match with the matched member's submitted Consent persisted on the responding side.
  • Five-year member history on demand: clinical, claims, encounters.
  • FHIR Consent resources with full audit trail of opt-in capture and revocation.

Caller and auth

PropertyValue
CallerReceiving payer (the new plan)
AuthenticationSMART Backend Services Authorization (asymmetric JWT, system-level scope)
Caller identityUDAP HL7 B2B organization_id claim in the access token
Token endpoint<base>/auth/token on the responding payer's deployment

The two payers exchange JWKS endpoints out-of-band (or pre-shared keys) at onboarding time. The caller's organization_id claim gates the opt-in export and is matched against the submitted Consent recipient (provision.actor[role=IRCP]).

See API Reference / Authentication.

CMS-0057-F prescribes opt-in for Payer-to-Payer. The receiving payer collects the member's opt-in during enrollment and stores the consent record. On $bulk-member-match, the receiving payer asserts the consent in the request payload. The responding payer validates the consent assertion before returning data.

Members can withdraw consent. Withdrawal is captured by the receiving payer and stops further requests.

Data scope

Five-year window of date-of-service, excluding remittances, cost-sharing, drug prior authorizations, and denied prior authorizations. See Compliance / CMS-0057 for the CFR anchor and full data-window rules.

Data classFHIR resourcesIG
USCDI v3 clinicalPatient, Condition, Observation, MedicationRequest, etc.US Core 6.1.0
Claims and encounters (no remittance, no cost-sharing)ExplanationOfBenefit (CARIN BB Non-Financial Basis profiles), CoveragePDex 2.1.0
Prior authorization request and decision (excluding drug PAs and denied PAs)ExplanationOfBenefit (use=preauthorization)PDex 2.1.0

The export enforces most of this scope server-side: ExplanationOfBenefit is floored to a 5-year service-date window, drug claims and drug PAs are dropped, and remittance / cost-sharing money fields are stripped from ExplanationOfBenefit and Coverage. Two gaps remain: denied prior authorizations are not yet filtered, and filtered resources carry Aidbox's SUBSETTED tag rather than the CARIN BB Non-Financial Basis profiles. Non-EOB clinical resources are date-bounded only if you pass _since. See $davinci-data-export.

Test dataset

Operation examples below reference this dataset. Load it first to reproduce them.

Load from the Aidbox REST Console — the bundle goes through the normal FHIR write path so AccessPolicies and Clients become active immediately:

Click to view test dataset bundle JSON 
POST /fhir
Content-Type: application/fhir+json

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "request": {"method": "PUT", "url": "/Client/test-payer-client"},
      "resource": {
        "resourceType": "Client",
        "id": "test-payer-client",
        "secret": "test-payer-secret",
        "grant_types": ["basic"],
        "details": {"identifier": [{"system": "http://hl7.org/fhir/sid/us-npi", "value": "5555555555"}]}
      }
    },
    {
      "request": {"method": "PUT", "url": "/Client/test-provider-client"},
      "resource": {
        "resourceType": "Client",
        "id": "test-provider-client",
        "secret": "test-provider-secret",
        "grant_types": ["basic"],
        "details": {"identifier": [{"system": "http://hl7.org/fhir/sid/us-npi", "value": "1982947230"}]}
      }
    },
    {
      "request": {"method": "PUT", "url": "/AccessPolicy/allow-test-payer-client"},
      "resource": {
        "resourceType": "AccessPolicy",
        "id": "allow-test-payer-client",
        "engine": "allow",
        "link": [{"resourceType": "Client", "id": "test-payer-client"}]
      }
    },
    {
      "request": {"method": "PUT", "url": "/AccessPolicy/allow-test-provider-client"},
      "resource": {
        "resourceType": "AccessPolicy",
        "id": "allow-test-provider-client",
        "engine": "allow",
        "link": [{"resourceType": "Client", "id": "test-provider-client"}]
      }
    },
    {
      "request": {"method": "PUT", "url": "/Organization/test-payer-001"},
      "resource": {
        "resourceType": "Organization",
        "id": "test-payer-001",
        "name": "Test Payer Organization",
        "identifier": [{"system": "http://hl7.org/fhir/sid/us-npi", "value": "5555555555"}]
      }
    },
    {
      "request": {"method": "PUT", "url": "/Organization/test-provider-001"},
      "resource": {
        "resourceType": "Organization",
        "id": "test-provider-001",
        "name": "Test Provider Organization",
        "identifier": [{"system": "http://hl7.org/fhir/sid/us-npi", "value": "1982947230"}]
      }
    },
    {
      "request": {"method": "PUT", "url": "/Organization/other-payer-001"},
      "resource": {
        "resourceType": "Organization",
        "id": "other-payer-001",
        "name": "Other Payer (not the requester)",
        "identifier": [{"system": "http://hl7.org/fhir/sid/us-npi", "value": "9999999999"}]
      }
    },
    {
      "request": {"method": "PUT", "url": "/Patient/test-member-001"},
      "resource": {
        "resourceType": "Patient",
        "id": "test-member-001",
        "name": [{"family": "Johnson", "given": ["Robert"]}],
        "gender": "male",
        "birthDate": "1952-07-25",
        "identifier": [{"system": "http://example.org/member-id", "value": "M12345"}]
      }
    },
    {
      "request": {"method": "PUT", "url": "/Patient/test-member-002"},
      "resource": {
        "resourceType": "Patient",
        "id": "test-member-002",
        "name": [{"family": "Williams", "given": ["Sarah"]}],
        "gender": "female",
        "birthDate": "1985-03-12",
        "identifier": [{"system": "http://example.org/member-id", "value": "M67890"}]
      }
    },
    {
      "request": {"method": "PUT", "url": "/Coverage/test-coverage-001"},
      "resource": {
        "resourceType": "Coverage",
        "id": "test-coverage-001",
        "status": "active",
        "subscriberId": "SUB-001",
        "beneficiary": {"reference": "Patient/test-member-001"},
        "payor": [{"reference": "Organization/test-payer-001"}]
      }
    },
    {
      "request": {"method": "PUT", "url": "/Coverage/test-coverage-002"},
      "resource": {
        "resourceType": "Coverage",
        "id": "test-coverage-002",
        "status": "active",
        "subscriberId": "SUB-002",
        "beneficiary": {"reference": "Patient/test-member-002"},
        "payor": [{"reference": "Organization/test-payer-001"}]
      }
    },
    {
      "request": {"method": "PUT", "url": "/Consent/test-optout-member-002"},
      "resource": {
        "resourceType": "Consent",
        "id": "test-optout-member-002",
        "status": "active",
        "scope": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/consentscope", "code": "patient-privacy"}]},
        "patient": {"reference": "Patient/test-member-002"},
        "category": [{"coding": [{"system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/pdex-consent-api-purpose", "code": "provider-access"}]}],
        "provision": {"type": "deny"},
        "policyRule": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "OPTIN"}]}
      }
    }
  ]
}

Operations

$bulk-member-match

The receiving payer submits one or more MemberBundle parameters — each carrying a MemberPatient (demographics), CoverageToMatch, and an opt-in HRex Consent whose provision.actor[role=IRCP] recipient identifies the receiving payer. The operation is always asynchronous — the kick-off returns 202 Accepted with Content-Location; when polled, the manifest points at an ndjson Parameters resource holding up to three inline Group resources.

The example below uses test-member-001 (Johnson, Robert) from the Test dataset, submitted by test-payer-client:

POST <base>/fhir/Group/$bulk-member-match
Authorization: Basic dGVzdC1wYXllci1jbGllbnQ6dGVzdC1wYXllci1zZWNyZXQ=
Prefer: respond-async
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "MemberBundle",
    "part": [
      {"name": "MemberPatient", "resource": {
        "resourceType": "Patient",
        "name": [{"family": "Johnson", "given": ["Robert"]}],
        "gender": "male", "birthDate": "1952-07-25"
      }},
      {"name": "CoverageToMatch", "resource": {
        "resourceType": "Coverage", "status": "active",
        "subscriberId": "SUB-001",
        "beneficiary": {"reference": "Patient/test-member-001"},
        "payor": [{"reference": "Organization/test-payer-001"}]
      }},
      {"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/test-member-001"},
        "dateTime": "2026-04-01T08:00:00Z",
        "policy": [{"uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#sensitive"}],
        "provision": {
          "type": "permit",
          "period": {"start": "2026-01-01T00:00:00Z", "end": "2027-01-01T00:00:00Z"},
          "actor": [{
            "role": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType", "code": "IRCP"}]},
            "reference": {"reference": "Organization/test-payer-001"}
          }]
        }
      }}
    ]
  }]
}

Three buckets in the response:

GroupProfileContents
MatchedMemberspdex-member-match-groupMembers matched, consent valid, opt-out clear; submitted Consent is persisted by the responding payer
NonMatchedMemberspdex-member-no-match-groupNo match found
ConsentConstrainedMemberspdex-member-no-match-group (code consentconstraint)Matched member with active opt-out, expired consent, or consent that could not be persisted

$bulk-member-match rejects non-admin callers whose access token lacks the hl7-b2b organization_id claim with 403.

See API Reference / Operations / $bulk-member-match.

$davinci-data-export with payertopayer exportType

The receiving payer triggers export on the MatchedMembers group:

POST <base>/fhir/Group/<matched-group-id>/$davinci-data-export
Authorization: Bearer <access-token>
Content-Type: application/fhir+json
Prefer: respond-async

{
  "resourceType": "Parameters",
  "parameter": [
    {"name": "exportType", "valueCanonical": "hl7.fhir.us.davinci-pdex#payertopayer"}
  ]
}

Response: 202 Accepted with Content-Location. On completion, the Aidbox $export-status manifest carries pre-signed ndjson URLs grouped by resource type.

See API Reference / Operations / $davinci-data-export.

Last updated: