Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 5 additions & 6 deletions docs/api-reference/operations/bulk-member-match.md
Original file line number Diff line number Diff line change
Expand Up @@ -470,9 +470,9 @@ URL comes from `output[0].url` in the manifest. Body is a single ndjson line —

| Direction | Parameter | Type | Cardinality | Description |
|---|---|---|---|---|
| OUT | `MatchedMembers` | Group | 1..1 | [`pdex-member-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-match-group.html); members matched, consent passed, opt-out clear, and the submitted Consent persisted. Group id is the input to [`$davinci-data-export`](davinci-data-export.md) with `exportType = hl7.fhir.us.davinci-pdex#payertopayer`. Each member links to the Patient the requesting payer submitted, carried in `Group.contained[]`, through the `base-ext-match-parameters` extension on `member.entity`. `quantity = 0` and `member` omitted when empty. |
| OUT | `MatchedMembers` | Group | 1..1 | [`pdex-member-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-match-group.html); members matched, consent passed, and the submitted Consent persisted. Group id is the input to [`$davinci-data-export`](davinci-data-export.md) with `exportType = hl7.fhir.us.davinci-pdex#payertopayer`. Each member links to the Patient the requesting payer submitted, carried in `Group.contained[]`, through the `base-ext-match-parameters` extension on `member.entity`. `quantity = 0` and `member` omitted when empty. |
| OUT | `NonMatchedMembers` | Group | 0..1 | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html); no match found. Submitted Patients are carried in `Group.contained[]` (fragment refs `#submitted-1`, `#submitted-2`, …). |
| OUT | `ConsentConstrainedMembers` | Group | 0..1 | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html) with code `consentconstraint`; matched member whose Consent failed a match-time check, has an active opt-out, or whose Consent could not be persisted. |
| OUT | `ConsentConstrainedMembers` | Group | 0..1 | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html) with code `consentconstraint`; matched member whose Consent failed a match-time check or could not be persisted. |

### Example

Expand Down Expand Up @@ -632,21 +632,20 @@ Each submitted member is evaluated independently. Per-member failures never fail

**Demographic match.** Same algorithm as [`$provider-member-match`](provider-member-match.md#matching-behavior): all four of `family`, `given[0]`, `birthDate`, `gender` are required and queried against payer Patients. `Patient.identifier` entries become `identifier` search tokens (FHIR AND semantics — every submitted identifier must match). Identifier-AND is bulk-specific: [`$provider-member-match`](provider-member-match.md#matching-behavior) ignores submitted `Patient.identifier` entries, because provider-side systems carry MRNs the payer does not store. `Coverage.subscriberId`, when present, becomes `_has:Coverage:beneficiary:subscriber-id`. Zero or ambiguous (>1) results route to `NonMatchedMembers`.

**Match-time consent checks.** A matched member is moved to `ConsentConstrainedMembers` if **any** of the following is true (the opt-out category code below uses the `pdex-consent-api-purpose` CodeSystem from PDex 2.2.0):
**Match-time consent checks.** A matched member is moved to `ConsentConstrainedMembers` if **any** of the following is true:

| Check | Constrains when |
|---|---|
| `Consent.status` | not `"active"` |
| `Consent.provision.period` | absent, unparseable, or does not cover the current time |
| `Consent.provision.actor[role=IRCP]` recipient | does not resolve to the requesting payer's `Organization/<id>` reference |
| `Consent.policy[*].uri` | not `#sensitive` — `#regular` and missing/unknown policy URIs both constrain (fail-safe; Payerbox does not yet redact sensitive data, so non-`#sensitive` consents cannot be honored) |
| Active `provider-access` deny `Consent` on the matched Patient (opt-out) | any active hit; a failing opt-out query (non-2xx) fails safe to constrained |

The opt-out check reuses the same Aidbox search as [`$provider-member-match`](provider-member-match.md#matching-behavior): `Consent?patient=<id>&status=active&category=http://hl7.org/fhir/us/davinci-pdex/CodeSystem/pdex-consent-api-purpose|provider-access&provision-type=deny`.
A Provider Access opt-out on the matched Patient is not checked: it is the member's choice about sharing with providers, separate from the Payer-to-Payer permission the submitted Consent carries.

**Consent persistence.** For each remaining matched member the submitted `Consent` is upserted into Aidbox with a deterministic id (`SHA-1(payer-org-id|patient-id)`); `Consent.patient` is rewritten to the matched payer Patient and `Consent.organization` to the requesting payer's Organization (FHIR shape is `0..*`; today exactly one element is written). The persisted Consent is what the later `$davinci-data-export?exportType=payertopayer` query reads against. If persistence fails — including the case where the requesting payer's identifier has no `Organization` registered in the responding payer's Aidbox — the member is re-bucketed to `ConsentConstrainedMembers`.

**Stale Consent removal.** If a later `$bulk-member-match` for the same `(matched-patient, requesting-payer)` lands the member in `ConsentConstrainedMembers` (failed match-time check, opt-out hit, or persistence failure), the prior persisted `Consent` at the deterministic id is deleted (one batch `Bundle` for all pairs). Deleted rather than deactivated: the HRex Consent profile fixes `status = active`, so a status flip would `422`. `$davinci-data-export?exportType=payertopayer` fails closed on the missing permit.
**Stale Consent removal.** If a later `$bulk-member-match` for the same `(matched-patient, requesting-payer)` lands the member in `ConsentConstrainedMembers` (failed match-time check or persistence failure), the prior persisted `Consent` at the deterministic id is deleted (one batch `Bundle` for all pairs). Deleted rather than deactivated: the HRex Consent profile fixes `status = active`, so a status flip would `422`. `$davinci-data-export?exportType=payertopayer` fails closed on the missing permit.

## Group lifecycle

Expand Down
13 changes: 13 additions & 0 deletions docs/api-reference/operations/davinci-data-export.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,19 @@ Content-Type: application/fhir+json
{% endtab %}
{% endtabs %}

## Export tracking

After each kick-off, Payerbox records the export on the `Group` with the PDex 2.1.0 tracking extensions:

| Extension | On | Value |
|---|---|---|
| [`base-ext-members-opted-out`](https://hl7.org/fhir/us/davinci-pdex/STU2.1/StructureDefinition-base-ext-members-opted-out.html) | `Group` | Members left out by the consent rule: opted out for `provider-download`, no valid opt-in for `payertopayer` |
| [`base-ext-last-transmission`](https://hl7.org/fhir/us/davinci-pdex/STU2.1/StructureDefinition-base-ext-last-transmission.html) | each exported `Group.member` | The request's `_until`, or the kick-off time |
| [`base-ext-last-types`](https://hl7.org/fhir/us/davinci-pdex/STU2.1/StructureDefinition-base-ext-last-types.html) | each exported `Group.member` | The request's `_type`, when present |
| [`base-ext-last-typefilter`](https://hl7.org/fhir/us/davinci-pdex/STU2.1/StructureDefinition-base-ext-last-typefilter.html) | each exported `Group.member` | The request's `_typeFilter`, when present |

An opt-out counts only while its `provision.period` is in force. Members left out by the consent rule, or outside the requested `patient` subset, keep their previous values. Tracking is written after the `202`; a failure there does not affect the export.

## Status polling

### Endpoint
Expand Down
2 changes: 1 addition & 1 deletion docs/fhir-app-portal/developer-portal.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The dashboard splits registration into two sections. Pick by how the client auth
| OAuth grant | `authorization_code` | `client_credentials` |
| Register under | **Smart Apps** | **Backend Services** |
| Auth | Public or confidential; redirect + launch URL | JWKS URI or client secret |
| Scopes | `patient/*`, `user/*`, launch, OIDC | `system/*` only |
| Scopes | `patient/` read, launch, OIDC | `system/*` only |
| Use for | Patient- or provider-facing apps | Bulk export, server-to-server APIs |

Each client-type page covers its own registration, testing, submission, and status.
2 changes: 1 addition & 1 deletion docs/fhir-app-portal/smart-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ A SMART App is an interactive SMART on FHIR client: a user launches it in a brow
* **Confidentiality**: public or confidential; a confidential client is issued a secret
* **Redirect URL**: where users return after authorization
* **Launch URL**: your app's SMART launch endpoint
3. Set the **SMART on FHIR scopes** the app requests (`patient/*`, `user/*`, plus launch and OIDC scopes)
3. Set the **SMART on FHIR scopes** the app requests (`patient/` read scopes, plus launch and OIDC scopes)
4. Click **Create App**

You're redirected to the app's draft page to review, edit, or delete it.
Expand Down
4 changes: 2 additions & 2 deletions docs/interop-apis/payer-to-payer.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,9 +104,9 @@ Three buckets in the response:

| Group | Profile | Contents |
|---|---|---|
| `MatchedMembers` | [`pdex-member-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-match-group.html) | Members matched, consent valid, opt-out clear; submitted `Consent` is persisted by the responding payer |
| `MatchedMembers` | [`pdex-member-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-match-group.html) | Members matched, consent valid; submitted `Consent` is persisted by the responding payer |
| `NonMatchedMembers` | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html) | No match found |
| `ConsentConstrainedMembers` | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html) (code `consentconstraint`) | Matched member with active opt-out, expired consent, or consent that could not be persisted |
| `ConsentConstrainedMembers` | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html) (code `consentconstraint`) | Matched member with 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`.

Expand Down
10 changes: 9 additions & 1 deletion docs/prior-auth/crd.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,15 @@ Hook-context resources (context and prefetch content) are validated before they
FHIR_VALIDATION_LENIENT=true
```

In lenient mode, terminology display-name mismatches, referenced-resource profile mismatches, and context references that cannot be resolved (the referenced resources may exist only in the EHR's own store) are logged as warnings and the hook proceeds; only structural and profile errors fail the request. Default (unset) — strict. The same flag also controls [PAS submission validation](pas.md#validation-strictness).
In lenient mode, terminology display-name mismatches and referenced-resource profile mismatches are logged as warnings and the hook proceeds; only structural and profile errors fail the request. Default (unset) — strict. The same flag also controls [PAS submission validation](pas.md#validation-strictness).

Context references that cannot be resolved, even from the EHR's `fhirServer` (the referenced resources may exist only in the EHR's own store), fail the hook request unless a separate flag is set:

```
FHIR_VALIDATION_LENIENT_REFERENCES=true
```

With it, the hook proceeds without the unresolved references. Off by default.

## Supported hooks

Expand Down
32 changes: 32 additions & 0 deletions docs/releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,38 @@ description: "Notable changes across Payerbox: the Interop APIs, the Prior Auth

This page tracks notable changes across Payerbox: the Interop APIs, the Prior Auth (ePA) APIs, and the FHIR App Portal. Releases are listed newest first. The apps run on an Aidbox FHIR server; each component heading links to its image on Docker Hub.

## October 2026 (`2610`)

### Interop APIs [`2610`](https://hub.docker.com/r/healthsamurai/interop)

**Provider Access**

- [`$provider-member-match`](api-reference/operations/provider-member-match.md) now recognizes `IDSCL` opt-outs.
- Member matching and [export tracking](api-reference/operations/davinci-data-export.md#export-tracking) now ignore opt-outs that have expired or have not started.

### Prior Auth (ePA) APIs [`2610`](https://hub.docker.com/r/healthsamurai/prior-auth)

**PAS**

- Files attached inside a submitted questionnaire can now be stored in S3 instead of inside the request, and attachments can be sent as a link instead of the file itself. Set `SUBMIT_ATTACHMENT_OFFLOAD_QUESTIONNAIRE_RESPONSE=true` and `SUBMIT_ATTACHMENT_ACCEPT_URL=true` to enable them (off by default). See [`$submit-attachment`](api-reference/operations/submit-attachment.md).

**CRD**

- Lenient validation is now split in two. `FHIR_VALIDATION_LENIENT` still relaxes minor data mismatches. Accepting references to records Payerbox can't find now needs a separate setting, `FHIR_VALIDATION_LENIENT_REFERENCES=true`. If you relied on the old behavior, set both. See [CRD validation strictness](prior-auth/crd.md#validation-strictness).

### FHIR App Portal [`2610`](https://hub.docker.com/r/healthsamurai/fhir-app-portal)

**Member consent**

- The **Data sharing** page was redesigned: each choice is a card that shows its current state and opens its form in place, one at a time. See [Consent Panel](fhir-app-portal/member-portal/consent-panel.md).
- Completing the forms as an authorized representative is opt-in per deployment: set `MEMBER_CONSENT_REPRESENTATIVES_ENABLED=true` on the portal backend. Off by default: members complete the forms themselves, representative submissions and document uploads are refused, and Member Details shows no reviews. In `2609` it was always on. See [Authorized representatives](fhir-app-portal/member-portal/consent-panel.md#authorized-representatives) and [Consent Reviews](fhir-app-portal/consent-reviews.md).
- **Settings → Consent** was rebuilt for the plan administrator: one card holds the plan, the date Payer-to-Payer permissions end, and whether members can exclude sensitive records; an administrator whose plan is not in Aidbox yet can add it from the picker with a NAIC company code or a TIN. See [Consent Settings](fhir-app-portal/consent-settings.md).
- Other health plans that members can pick on the Payer-to-Payer form are registered by NAIC company code or TIN instead of NPI.

**MPF pipeline**

- The Bundle `entry.fullUrl` base is an admin setting in **Settings → MPF**, saved with the publications; unset, it resolves to the admin Aidbox public URL plus `/fhir`. With no publications saved, nothing is published. See [MPF Publications](fhir-app-portal/mpf-publications.md).

## September 2026 (`2609`)

- The [Data Integration Reference](data-integration/README.md) adds four feeds: [Claims](data-integration/carin-bb/README.md) (CARIN BB 2.1.0), [Prior Authorizations](data-integration/prior-auth/README.md) (PDex 2.1.0), [Drug Formulary](data-integration/drug-formulary/README.md) (PDex US Drug Formulary 2.1.0), and [Member Consent](data-integration/consent/README.md).
Expand Down
Loading