From ac0d4deac5086b782f5086af22edab4bfcad50db Mon Sep 17 00:00:00 2001 From: Andrey Fedorov Date: Wed, 15 Jul 2026 01:37:05 +0200 Subject: [PATCH 1/2] =?UTF-8?q?docs(prior-auth):=20document=20UM=20forward?= =?UTF-8?q?ing=20=E2=80=94=20UMTenantConfig=20and=20the=20pas-passthrough?= =?UTF-8?q?=20connector?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/prior-auth/pas.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/prior-auth/pas.md b/docs/prior-auth/pas.md index 05d6c4f..222c1ad 100644 --- a/docs/prior-auth/pas.md +++ b/docs/prior-auth/pas.md @@ -71,6 +71,35 @@ Accept: application/json Full Bundle profiles, all parameters, and edge cases: [Claim/$submit](../api-reference/operations/claim-submit.md). For status checks and attachment workflows: [Claim/$inquire](../api-reference/operations/claim-inquire.md), [$submit-attachment](../api-reference/operations/submit-attachment.md). +## Forwarding to the payer's UM system + +After `Claim/$submit` returns the queued `ClaimResponse`, Payerbox forwards the request to the payer's utilization management (UM) system for adjudication. Forwarding is configured per payer with a `UMTenantConfig` resource: incoming Claims are routed by matching `Claim.insurer` against the tenant's insurer reference or identifier, queued as a FHIR `Task`, and delivered by a background worker with retries. + +`UMTenantConfig.connector` selects the integration: + +| Connector | UM system contract | +|---|---| +| `guidingcare` | HealthEdge GuidingCare REST API, with ConceptMap-driven code translation | +| `pas-passthrough` | Any UM system that itself implements Da Vinci PAS: the request Bundle is forwarded to the delegate's own `Claim/$submit`, and status can be refreshed via its `Claim/$inquire` | + +With `pas-passthrough`, onboarding a PAS-conformant delegate is a configuration change only — no code changes or redeployment. The key `UMTenantConfig` elements: + +| Element | Purpose | +|---|---| +| `connector` | `guidingcare` or `pas-passthrough` | +| `insurer.reference` / `insurer.identifier` | Routing key matched against `Claim.insurer` | +| `endpoint.baseUrl` | UM system API base URL | +| `endpoint.auth` | `oauth2-client-credentials` (token URL + client id, secret resolved from an environment variable) or `api-key`. Secrets are referenced by environment variable name, never stored in the resource | +| `endpoint.timeoutMs` / `endpoint.connectTimeoutMs` | Per-attempt timeouts (defaults: 30000 / 10000 ms) | +| `endpoint.retry` | Delivery attempts and backoff (defaults: 5 attempts, 30s / 2m / 10m / 30m) | +| `inquireRefresh` | When `true`, `Claim/$inquire` fetches the live decision from the UM system instead of returning only the stored `ClaimResponse` | + +Delivery notes for `pas-passthrough`: + +- The delegate must implement Da Vinci PAS 2.1.0 `Claim/$submit` (and `Claim/$inquire` for status refresh). +- The forwarded Bundle carries the original submitter's transaction identifier as `Bundle.identifier`, and the Claim is forwarded with its original identifier (TRN). Retries of the same delivery carry the same identifiers, so a conformant delegate deduplicates them as PAS duplicate-TRN submissions. +- Ambiguous delivery failures (for example, a timeout after the delegate may have accepted the request) are parked for manual review rather than blindly retried. + ## Notifications Rather than polling `Claim/$inquire`, a downstream system can subscribe to decision events and be notified when a `ClaimResponse` is recorded. See [Event Notifications](event-notifications.md) for how to set up a FHIR topic-based subscription. From 755490e46e0064d6a9755c3018f8f10c35ef0f0f Mon Sep 17 00:00:00 2001 From: Andrey Fedorov Date: Wed, 15 Jul 2026 01:37:05 +0200 Subject: [PATCH 2/2] =?UTF-8?q?docs(api-reference):=20submit-attachment=20?= =?UTF-8?q?=E2=80=94=20canonical=20/fhir=20path,=20actual=20parameter=20co?= =?UTF-8?q?ntract?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api-reference/operations/submit-attachment.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/api-reference/operations/submit-attachment.md b/docs/api-reference/operations/submit-attachment.md index c4d5f9f..11c01e5 100644 --- a/docs/api-reference/operations/submit-attachment.md +++ b/docs/api-reference/operations/submit-attachment.md @@ -11,7 +11,7 @@ Unlike `Claim/$submit` and `Claim/$inquire`, this is a **system-level** operatio ## Endpoint ``` -POST /$submit-attachment +POST /fhir/$submit-attachment ``` ## Auth @@ -25,17 +25,23 @@ SMART Backend Services. Scope requirements depend on the attachment content type | TrackingId | Identifier | 1..1 | Correlation identifier tying attachments to a prior authorization (must match an existing Claim identifier) | | AttachTo | code | 1..1 | `"claim"` or `"preauthorization"` — indicates what the attachment relates to | | MemberId | Identifier | 1..1 | Patient member identifier | -| Final | boolean | 1..1 | Whether this is the final attachment submission for the given TrackingId | | Attachment | BackboneElement | 1..* | Container for attachment content and metadata (see sub-parameters below) | +| Final | boolean | 0..1 | Whether this is the final attachment submission for the given TrackingId. Defaults to `true` when omitted | +| PayerId | Identifier | 0..1 | Payer identifier | +| OrganizationId | Identifier | 0..1 | Submitting organization identifier | +| ProviderId | Identifier | 0..1 | Provider identifier | +| ServiceDate | dateTime | 0..1 | Date of service the attachment relates to | +| AdminRefNumber | Identifier | 0..1 | Administrative reference number for the prior authorization | {% hint style="info" %} -The CDex profile enforces a minimum of 5 elements in the `parameter` array. All five parameters listed above must be present to pass validation. +`TrackingId`, `AttachTo`, `MemberId`, and at least one `Attachment` are required. Requests missing any of these four parameters fail validation with HTTP 422. {% endhint %} **Attachment sub-parameters** (nested `part` elements): | Sub-parameter | Type | Cardinality | Description | |---|---|---|---| +| LineItem | string | 0..* | Claim line item number(s) the attachment applies to | | Code | CodeableConcept | 0..1 | LOINC or PWK01 code identifying the attachment type. When provided, it is stored in the Claim's `supportingInfo.code` | | Content | Resource | 1..1 | The FHIR resource containing the attachment data (e.g., `DocumentReference`, `Bundle`, `QuestionnaireResponse`, `Observation`) | @@ -61,7 +67,7 @@ The CDex profile enforces a minimum of 5 elements in the `parameter` array. All {% tab title="Request" %} ```http -POST /$submit-attachment +POST /fhir/$submit-attachment Content-Type: application/json Accept: application/json