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)
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.

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 five-year date-of-service window, the remittance / cost-sharing / drug-PA / denied-PA exclusions, and the CARIN BB Non-Financial Basis profiling above describe the target data scope; they are not yet enforced server-side. The export currently returns the Group's full resource set, so narrow it explicitly with _type / _typeFilter / _since.

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 callers whose requesting-payer identity cannot be resolved from the OAuth client 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: