priorauth-sdk

Installation · Quick Start · Operations · Contributing · Security

Focused Python models and Bundle helpers for HL7 Da Vinci Prior Authorization Support (PAS)

Status: Alpha · License: Apache-2.0 · FHIR: R4 (4.0.1) · PAS: 2.2.1

1. What problem does this solve?

CMS-0057-F generally requires impacted payers to support FHIR-based prior authorization APIs beginning January 1, 2027. Teams preparing for that deadline repeatedly need to assemble and interpret the same PAS Claim and ClaimResponse structures.

priorauth-sdk supplies a small, typed Python layer for that work. It builds self-contained request Bundles, parses common authorization decisions, and catches focused structural errors without adding an HTTP client or payer decision logic.

This package is not a legal-compliance opinion, an X12 implementation, or a replacement for validation against the complete PAS Implementation Guide.

Capability	Included
Typed request and outcome models	✅
Submit and inquiry Bundle builders	✅
Response decision parsing	✅
Focused structural validation	✅
Network transport or authentication	—
Payer decision logic	—

How it works

flowchart LR
    A[Python request] --> B[priorauth-sdk builder]
    B --> C[FHIR PAS Bundle]
    C --> D[Your HTTP client]
    D --> E[Payer PAS API]
    E --> F[ClaimResponse]
    F --> G[priorauth-sdk parser]
    G --> H[Approved / denied / pended / partial]

Loading

The SDK owns the conversion and validation steps shown above. Your application remains responsible for authentication and sending the Bundle to a payer endpoint.

2. Features

• Pydantic v2 request and outcome models with FHIR-compatible JSON aliases
• Submit Bundles for POST [base]/Claim/$submit
• Query-by-example Bundles for POST [base]/Claim/$inquire
• Approved, denied, pended, and partial response parsing
• Coded denial reasons and per-item adjudication details
• Focused structural validation with stable issue codes and paths
• No HTTP, authentication, PHI, or payer-specific business logic

3. Installation

Install directly from GitHub

python -m pip install "git+https://github.com/PeerbitsSolution/priorauth-sdk.git"

For reproducible deployments, install a specific GitHub release tag:

python -m pip install "git+https://github.com/PeerbitsSolution/priorauth-sdk.git@v0.1.0"

Clone and install locally

git clone https://github.com/PeerbitsSolution/priorauth-sdk.git
cd priorauth-sdk
python -m pip install .

For development, install the checked-out repository with its test and quality tools:

python -m pip install -e ".[dev]"

Requirements: Git and Python 3.10 or newer.

4. Demo and Quick Start

Peerbits HealthTech - PriorAuth-SDK Demo

The builder accepts a simplified typed request plus the lightweight FHIR resources referenced by the Claim. All identifiers below are invented.

from datetime import datetime, timezone

from priorauth_sdk import (
    CodeableConcept,
    Coding,
    FHIRReference,
    Identifier,
    PriorAuthItem,
    PriorAuthRequest,
    Quantity,
    ReferencedResource,
    build_prior_auth_submit_bundle,
)

resources = (
    ReferencedResource(fullUrl="urn:uuid:patient", resource={"resourceType": "Patient", "id": "patient"}),
    ReferencedResource(fullUrl="urn:uuid:payer", resource={"resourceType": "Organization", "id": "payer"}),
    ReferencedResource(fullUrl="urn:uuid:provider", resource={"resourceType": "Organization", "id": "provider"}),
    ReferencedResource(fullUrl="urn:uuid:coverage", resource={"resourceType": "Coverage", "id": "coverage"}),
)

request = PriorAuthRequest(
    bundle_identifier=Identifier(system="urn:example:transactions", value="submit-001"),
    claim_identifier=Identifier(system="urn:example:claims", value="claim-001"),
    claim_full_url="urn:uuid:claim",
    created=datetime(2026, 8, 10, tzinfo=timezone.utc),
    patient_ref=FHIRReference(reference="urn:uuid:patient"),
    insurer_ref=FHIRReference(reference="urn:uuid:payer"),
    provider_ref=FHIRReference(reference="urn:uuid:provider"),
    coverage_ref=FHIRReference(reference="urn:uuid:coverage"),
    priority="normal",
    items=(
        PriorAuthItem(
            sequence=1,
            product_or_service=CodeableConcept(
                coding=(Coding(system="http://example.org/synthetic/services", code="SERVICE"),)
            ),
            quantity=Quantity(value=1),
        ),
    ),
    resources=resources,
)

bundle = build_prior_auth_submit_bundle(request)
payload = bundle.to_fhir_dict()

The result is JSON-ready and starts with the PAS Claim:

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "fullUrl": "urn:uuid:claim",
      "resource": {
        "resourceType": "Claim",
        "use": "preauthorization",
        "priority": {
          "coding": [{"code": "normal"}]
        }
      }
    }
  ]
}

Pass payload to the FHIR HTTP client of your choice. Network transport and authentication are deliberately outside this package.

5. Architecture

The public surface is split into immutable Pydantic models, pure Bundle builders, focused validators, and a response parser. Builders return typed FHIRBundle values; call to_fhir_dict() before JSON encoding.

See PAS Operations Reference for the operation-level wire shapes and Terminology and IP before using licensed code systems.

6. Beginner Examples

Clone the repository and install it before running the examples:

git clone https://github.com/PeerbitsSolution/priorauth-sdk.git
cd priorauth-sdk
python -m pip install .

Then run any example directly:

Example	Command	What it demonstrates
Submit request	python examples/build_submit_bundle.py	Builds a PAS submit Bundle from typed Python input
Status inquiry	python examples/build_inquiry_bundle.py	Builds a query-by-example PAS inquiry Bundle
Parse response	python examples/parse_response.py	Converts a denied ClaimResponse into a simple typed result
Validate Claim	python examples/validate_claim.py	Reports the exact error in an invalid Claim

Every example prints JSON and uses only obvious synthetic data. None of the scripts makes a network request. See examples/README.md for a guided explanation and fixtures/ for the underlying request and response payloads.

7. Scope and Conformance

The package targets the focused data surface described in the project handover and pins its behavior to published Da Vinci PAS 2.2.1. Extra PAS fields can be preserved through additional_claim_fields, but builder-managed fields cannot be overridden.

validate_pas_claim and validate_pas_claim_response are structural self-checks only. Production integrations must still validate against the complete PAS profiles, applicable terminology, security requirements, payer rules, and any relevant X12 requirements.

8. Roadmap

• PAS/RCM subject-matter review and external conformance validation before 1.0.0
• Update and cancellation convenience builders using $submit
• Broader PAS profile coverage
• Separate CRD and DTR integration helpers

9. Contributing and Security

See CONTRIBUTING.md before opening a pull request. Report security problems using SECURITY.md, not a public issue.

Never contribute real patient, member, provider, payer, coverage, claim, authorization, or client data.

10. License and Project

Apache License 2.0 — see LICENSE. Third-party terminology remains subject to its owners' terms; see NOTICE.

Maintained under the PeerbitsSolution organization and distributed directly from GitHub. See RELEASE_CHECKLIST.md for optional post-push repository settings and stable-release review gates.