For AI agents: the documentation index is at /docs/payerbox/llms.txt. A Markdown version of this page is available at /docs/payerbox/prior-auth/pas.md or by requesting it with the Accept: text/markdown header.
Payerbox Docs

PAS

The Payerbox PAS API enables direct submission of prior authorization requests from EHR/UM systems using FHIR. Built on the HL7 Da Vinci Prior Authorization Support Implementation Guide.

When combined with CRD and DTR, PAS ensures authorizations are submitted when necessary with all required information for initial decision-making.

Payerbox implements Da Vinci PAS STU 2.1.0. See Compliance / CMS-0057 for the regulatory context.

Lifecycle

PAS supports three operations forming a typical flow:

  1. Claim/$submit — Submit a prior authorization request as a FHIR Bundle. Payerbox returns a ClaimResponse with outcome = "queued"; the payer's UM system later updates the same ClaimResponse to convey the decision via the reviewAction extension (e.g. X12 code A1 = certified / approved, A3 = not certified / denied, A4 = pended).
  2. Claim/$inquire — Poll the status of a previously submitted request.
  3. $submit-attachment — (Optional) Submit clinical documentation associated with an existing prior authorization, when the payer requests additional information.

The Da Vinci PAS Request Bundle profile requires exactly one focal Claim per Bundle — the underlying X12 278 transaction carries one prior authorization per BHT. Submit multiple requests with multiple Claim/$submit calls.

Changing or cancelling an authorization is another Claim/$submit call with a new Claim pointing at the previous one through Claim.related. Under PAS 2.1.0 it reuses the original ClaimResponse instead of creating a second one, and an update to an already denied authorization is rejected. See Update flow.

Authentication

PAS uses SMART Backend Services Authorization. The payer admin provisions Client credentials per partner integration (EHR vendor, UM vendor, integrator). See API Reference / Authentication for the onboarding and token exchange flow.

Example

Submit a prior authorization. The payloads below are abbreviated to show the shape — elements the PAS profiles require (Claim.identifier, Claim.item, the MB-typed member identifier on Patient, entry fullUrls, the referenced Organization resources, and more) are elided, so this exact Bundle would be rejected by validation. For a complete request that passes strict validation, see Claim/$submit.

POST /fhir/Claim/$submit
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Bundle",
  "meta": { "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-request-bundle"] },
  "type": "collection",
  "identifier": { "system": "http://example.org/PATIENT_EVENT_TRACE_NUMBER", "value": "trace-0001" },
  "timestamp": "2025-12-08T16:48:02Z",
  "entry": [
    { "resource": { "resourceType": "Claim", "id": "claim-1", "status": "active", "use": "preauthorization", "patient": { "reference": "Patient/patient-1" }, "insurer": { "reference": "Organization/payer-org-1" } } },
    { "resource": { "resourceType": "Patient", "id": "patient-1", "name": [{ "family": "Smith", "given": ["John"] }] } },
    { "resource": { "resourceType": "Coverage", "id": "coverage-1", "status": "active", "beneficiary": { "reference": "Patient/patient-1" } } }
  ]
}

{
  "resourceType": "Bundle",
  "meta": { "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-response-bundle"] },
  "type": "collection",
  "identifier": { "system": "http://example.org/PATIENT_EVENT_TRACE_NUMBER", "value": "trace-0001" },
  "timestamp": "2025-12-08T16:48:03Z",
  "entry": [
    {
      "fullUrl": "<base>/fhir/ClaimResponse/62424909-3c59-4a09-be78-2032c4e081f5",
      "resource": {
        "resourceType": "ClaimResponse",
        "id": "62424909-3c59-4a09-be78-2032c4e081f5",
        "status": "active",
        "use": "preauthorization",
        "outcome": "queued",
        "request": { "reference": "Claim/claim-1" }
      }
    }
  ]
}

The real response Bundle carries the ClaimResponse first, followed by the resources it references, each with an absolute fullUrl under the deployment's FHIR base URL.

Full Bundle profiles, all parameters, and edge cases: Claim/$submit. For status checks and attachment workflows: Claim/$inquire, $submit-attachment.

Validation strictness

Every Claim/$submit Bundle is validated against the Da Vinci PAS profiles before anything is persisted. By default validation is strict: any error-level finding rejects the submission with 422 and an OperationOutcome listing all findings.

Operators can relax this per deployment:

FHIR_VALIDATION_LENIENT=true

In lenient mode, findings that do not affect the integrity of the submission — terminology display-name mismatches and referenced-resource profile mismatches — are logged as warnings instead of rejecting the request, and a 422 response body carries only the blocking findings. Structural errors, profile violations, and references to resources missing from the Bundle still reject the submission.

Lenient mode is intended for sandbox and onboarding environments, where trading partners iterate on their payloads and cosmetic findings should not block end-to-end testing. Keep production deployments strict. Default (unset) — strict. The same flag also controls CRD hook-context validation.

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 and writes the decision back onto the same ClaimResponse. Forwarding is enabled per payer with a UMTenantConfig resource; with no matching config the request is stored and stays queued.

See UM System Integration for the connectors, the delivery lifecycle and its limitations.

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 for how to set up a FHIR topic-based subscription.

Recording inquiry exchanges

Claim/$inquire is a read operation and stores nothing by default. Two of the PAS metrics — the query bucket of metric 2 and metric 3 — measure query exchanges, so they stay empty unless the deployment records them:

PAS_PERSIST_INQUIRIES=true

With the flag on, every successful $inquire stores a compact exchange record: an AuditEvent whose subtype carries the http://prior-auth.example.org/CodeSystem/pas-exchange-type|query coding, with recorded set to the time the request was received, agent.who pointing at the inquiring provider (resolved to a stored resource by NPI), and entity.what referencing the Claim the inquiry resolved to. The record is written by the prior-auth service itself, independent of the Aidbox audit log setting, and never appears in $inquire responses; a recording failure is logged without affecting the response. Each successful inquiry is one record of a couple of KB; unmatched inquiries are not recorded. Notification topics on Claim or ClaimResponse are unaffected.

Default (unset) — off.

Metrics

Payerbox ships with Da Vinci PAS Implementation Guide's suggested PAS metrics that are calculated directly from stored FHIR data.

Last updated: