diff --git a/docs/api-reference/operations/claim-inquire.md b/docs/api-reference/operations/claim-inquire.md index 31facac..72289da 100644 --- a/docs/api-reference/operations/claim-inquire.md +++ b/docs/api-reference/operations/claim-inquire.md @@ -12,6 +12,14 @@ Checks the status of a previously submitted prior authorization request, defined POST /fhir/Claim/$inquire ``` +### Update chains + +A prior authorization is updated or cancelled by submitting a new `Claim` that points at the prior one through `Claim.related` (relationship `prior`, or the legacy `replaces`). Under PAS 2.1.0 the decision `ClaimResponse` stays on the original (root) `Claim` of the chain; update and cancel `Claim`s carry none of their own. + +From any `Claim` in the chain, `$inquire` walks `Claim.related` backward to the root and returns that `Claim`'s latest `ClaimResponse`. Inquiring on the original `Claim`, an intermediate update, or the newest update returns the same `ClaimResponse`. Cycle and depth guards stop a malformed chain from looping. + +Under the legacy 2.0.1 model each `Claim` in a chain carried its own `ClaimResponse`, and `$inquire` resolved forward to the newest one. Payerbox behavior, not a PAS profile element. + ## Auth SMART Backend Services. Scope: `system/Claim.r system/ClaimResponse.r`. See [Authentication](../authentication.md). @@ -113,12 +121,4 @@ Accept: application/json {% endtab %} {% endtabs %} -## Update chains - -A prior authorization is updated or cancelled by submitting a new `Claim` that points at the prior one through `Claim.related` (relationship `prior`, or the legacy `replaces`). Under PAS 2.1.0 the decision `ClaimResponse` stays on the original (root) `Claim` of the chain; update and cancel `Claim`s carry none of their own. - -From any `Claim` in the chain, `$inquire` walks `Claim.related` backward to the root and returns that `Claim`'s latest `ClaimResponse`. Inquiring on the original `Claim`, an intermediate update, or the newest update returns the same `ClaimResponse`. Cycle and depth guards stop a malformed chain from looping. - -Under the legacy 2.0.1 model each `Claim` in a chain carried its own `ClaimResponse`, and `$inquire` resolved forward to the newest one. Payerbox behavior, not a PAS profile element. - See [Claim/$submit](claim-submit.md#claimresponse-link), [PAS](../../prior-auth/pas.md). diff --git a/docs/api-reference/operations/claim-submit.md b/docs/api-reference/operations/claim-submit.md index 6f403c7..613ffe0 100644 --- a/docs/api-reference/operations/claim-submit.md +++ b/docs/api-reference/operations/claim-submit.md @@ -14,6 +14,25 @@ The Da Vinci PAS Request Bundle profile requires exactly one focal `Claim` per B POST /fhir/Claim/$submit ``` +### ClaimResponse link + +Before persisting, Payerbox links the `Claim` to its `ClaimResponse`: the stored `Claim` carries an extension whose `valueReference` points at the `ClaimResponse`. + +```json +{ + "url": "https://fhir.aidbox.app/fhir/StructureDefinition/claim-response-reference", + "valueReference": { "reference": "ClaimResponse/c0d73c37-12ee-4cde-bfc6-aa6ed216f4dd" } +} +``` + +The id rides along on the `Claim` in [change notifications](../../prior-auth/event-notifications.md), so a consumer correlates the pair without a separate `ClaimResponse` search. Present on initial submits and on PAS 2.1.0 update/cancel requests, which reuse the prior authorization's original `ClaimResponse` instead of minting a new one. Payerbox behavior, not a PAS profile element. + +### Duplicate submissions + +A submission is matched against existing claims by the first `Claim.identifier` (its `system` and `value`). If a claim with the same identifier already exists, `$submit` returns its latest `ClaimResponse` and creates nothing new. This makes retries safe: resending the same bundle does not fork the authorization into a second record. + +Matching uses only the identifier. Changed `item[]` content does not create a new claim; to change a prior authorization, submit a new `Claim` (new `Claim.identifier`) whose `Claim.related` points at the previous `Claim` with relationship `prior` (PAS 2.1.0; the legacy `replaces` code is also accepted). An update `$submit` returns the [original Claim's `ClaimResponse`](#claimresponse-link) rather than minting a new one. Identifiers without both `system` and `value` are not matched and always create a new claim. + ## Auth SMART Backend Services. Scope: `system/Claim.cu system/ClaimResponse.r`. See [Authentication](../authentication.md). @@ -185,22 +204,3 @@ Accept: application/json {% endtab %} {% endtabs %} - -## ClaimResponse link - -Before persisting, Payerbox links the `Claim` to its `ClaimResponse`: the stored `Claim` carries an extension whose `valueReference` points at the `ClaimResponse`. - -```json -{ - "url": "https://fhir.aidbox.app/fhir/StructureDefinition/claim-response-reference", - "valueReference": { "reference": "ClaimResponse/c0d73c37-12ee-4cde-bfc6-aa6ed216f4dd" } -} -``` - -The id rides along on the `Claim` in [change notifications](../../prior-auth/event-notifications.md), so a consumer correlates the pair without a separate `ClaimResponse` search. Present on initial submits and on PAS 2.1.0 update/cancel requests, which reuse the prior authorization's original `ClaimResponse` instead of minting a new one. Payerbox behavior, not a PAS profile element. - -## Duplicate submissions - -A submission is matched against existing claims by the first `Claim.identifier` (its `system` and `value`). If a claim with the same identifier already exists, `$submit` returns its latest `ClaimResponse` and creates nothing new. This makes retries safe: resending the same bundle does not fork the authorization into a second record. - -Matching uses only the identifier. Changed `item[]` content does not create a new claim; to change a prior authorization, submit a new `Claim` (new `Claim.identifier`) whose `Claim.related` points at the previous `Claim` with relationship `prior` (PAS 2.1.0; the legacy `replaces` code is also accepted). An update `$submit` returns the [original Claim's `ClaimResponse`](#claimresponse-link) rather than minting a new one. Identifiers without both `system` and `value` are not matched and always create a new claim. diff --git a/docs/api-reference/operations/davinci-data-export.md b/docs/api-reference/operations/davinci-data-export.md index dc24983..65288a7 100644 --- a/docs/api-reference/operations/davinci-data-export.md +++ b/docs/api-reference/operations/davinci-data-export.md @@ -53,6 +53,19 @@ The request body must be a FHIR `Parameters` resource. Unsupported parameter nam +### exportType values + +| Value | Used by | Consent rule | Data scope | +|---|---|---|---| +| `hl7.fhir.us.davinci-pdex#provider-download` | Provider Access | Member opt-out (`consentStrategy=opt-out`, PDex Provider Consent, `provision.type=deny`) | Full member record, minus drug claims / drug PAs and money fields | +| `hl7.fhir.us.davinci-pdex#payertopayer` | Payer-to-Payer | Active opt-in `Consent` asserted at `$bulk-member-match` time (`consentStrategy=opt-in`, HRex Consent) | Same as `provider-download`, plus `ExplanationOfBenefit` floored to a 5-year `service-date` window | + +Denied PAs are not yet excluded, and a caller `_typeFilter` naming `ExplanationOfBenefit` is rejected with `400`. + +{% hint style="info" %} +Financial filtering requires Aidbox's `fhir.bulk-data.export.nested-elements` setting. The [Quickstart Docker Compose](../../get-started/quickstart-run-locally.md) turns it on via `BOX_FHIR_BULK_DATA_EXPORT_NESTED_ELEMENTS`; see [Aidbox nested `_elements`](https://www.health-samurai.io/docs/aidbox/api/bulk-api/export#nested-elements). +{% endhint %} + ### Example {% tabs %} @@ -278,19 +291,6 @@ HTTP/1.1 202 Accepted {% endtab %} {% endtabs %} -## exportType values - -| Value | Used by | Consent rule | Data scope | -|---|---|---|---| -| `hl7.fhir.us.davinci-pdex#provider-download` | Provider Access | Member opt-out (`consentStrategy=opt-out`, PDex Provider Consent, `provision.type=deny`) | Full member record, minus drug claims / drug PAs and money fields | -| `hl7.fhir.us.davinci-pdex#payertopayer` | Payer-to-Payer | Active opt-in `Consent` asserted at `$bulk-member-match` time (`consentStrategy=opt-in`, HRex Consent) | Same as `provider-download`, plus `ExplanationOfBenefit` floored to a 5-year `service-date` window | - -Denied PAs are not yet excluded, and a caller `_typeFilter` naming `ExplanationOfBenefit` is rejected with `400`. - -{% hint style="info" %} -Financial filtering requires Aidbox's `fhir.bulk-data.export.nested-elements` setting. The [Quickstart Docker Compose](../../get-started/quickstart-run-locally.md) turns it on via `BOX_FHIR_BULK_DATA_EXPORT_NESTED_ELEMENTS`; see [Aidbox nested `_elements`](https://www.health-samurai.io/docs/aidbox/api/bulk-api/export#nested-elements). -{% endhint %} - ## Errors | Status | Where | Cause |