> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Healthcare Prior Authorization

> Govern prior authorization decisions for medical procedures and medications

## Scenario

A healthcare technology platform automates prior authorization (PA) requests from providers. Before approving coverage for a procedure or medication, the system must evaluate clinical and administrative signals against the payer's coverage policy.

Requirements:

* Every PA decision must be signed and independently verifiable by providers and auditors
* Urgent/emergency requests receive immediate authorization but require post-authorization clinical review
* Decisions must reproduce from the original clinical signals for retrospective audit
* HIPAA-relevant: no patient identifiers in signals use member/plan IDs and clinical codes only

***

## Policy

Create `policies/prior-auth/1.0.0/policy.json`:

```json theme={null}
{
  "policyId": "prior-auth",
  "policyVersion": "1.0.0",
  "schemaVersion": "1.0.0",
  "signalsSchema": {
    "procedureCode":       { "type": "string" },
    "diagnosisCode":       { "type": "string" },
    "memberPlanTier":      { "type": "string" },
    "providerNetwork":     { "type": "string" },
    "estimatedCost":       { "type": "number" },
    "urgency":             { "type": "string" },
    "priorAuthCount":      { "type": "integer" },
    "treatmentDuration":   { "type": "integer" }
  },
  "rules": [
    {
      "id": "emergency-approve",
      "condition": { "signal": "urgency", "equals": "emergency" },
      "outcome": {
        "action": "approve",
        "requires_override": false,
        "reason": "Emergency authorization granted. Clinical review required post-treatment."
      }
    },
    {
      "id": "out-of-network-review",
      "condition": { "signal": "providerNetwork", "equals": "out_of_network" },
      "outcome": {
        "action": "clinical_review",
        "requires_override": true,
        "reason": "Prior authorization requires clinical review: out-of-network provider."
      }
    },
    {
      "id": "high-cost-review",
      "condition": { "signal": "estimatedCost", "greater_than": 25000 },
      "outcome": {
        "action": "clinical_review",
        "requires_override": true,
        "reason": "Prior authorization requires clinical review: estimated cost exceeds threshold."
      }
    },
    {
      "id": "repeat-auth-review",
      "condition": { "signal": "priorAuthCount", "greater_than": 5 },
      "outcome": {
        "action": "clinical_review",
        "requires_override": true,
        "reason": "Prior authorization requires clinical review: high utilization pattern."
      }
    },
    {
      "id": "standard-approve",
      "condition": { "all": [] },
      "outcome": {
        "action": "approve",
        "requires_override": false,
        "reason": "Prior authorization approved: within standard coverage parameters."
      }
    }
  ]
}
```

***

## Complete TypeScript example

```typescript theme={null}
import { ParmanaClient, ParmanaApiError } from "@parmanasystems/sdk-client";
import type { ExecutionAttestation } from "@parmanasystems/sdk-client";

const client = new ParmanaClient({
  baseUrl: process.env.PARMANA_URL ?? "http://localhost:3000",
  apiKey: process.env.PARMANA_API_KEY,
});

// Signals use clinical codes and plan/network identifiers — no PHI
interface PriorAuthSignals {
  procedureCode: string;        // CPT code
  diagnosisCode: string;        // ICD-10 code
  memberPlanTier: string;       // "basic" | "standard" | "premium"
  providerNetwork: string;      // "in_network" | "out_of_network"
  estimatedCost: number;        // USD
  urgency: string;              // "routine" | "urgent" | "emergency"
  priorAuthCount: number;       // prior auths for this member+procedure in last 12 months
  treatmentDuration: number;    // days
}

interface PriorAuthResult {
  authorizationId: string;
  approved: boolean;
  pendingClinicalReview: boolean;
  action: string;
  reason: string;
  attestation: ExecutionAttestation;
}

async function requestPriorAuth(
  authorizationId: string,
  signals: PriorAuthSignals
): Promise<PriorAuthResult> {
  const attestation = await client.execute({
    executionId: authorizationId,
    policyId: "prior-auth",
    policyVersion: "1.0.0",
    signals,
  });

  // Verify before returning — attestation must be valid before any clinical action
  const verification = await client.verify(attestation);
  if (!verification.valid) {
    throw new Error(
      `Attestation verification failed for authorization ${authorizationId}. ` +
      `Authorization cannot be granted.`
    );
  }

  return {
    authorizationId,
    approved:
      attestation.execution_state === "completed" &&
      attestation.decision.action === "approve",
    pendingClinicalReview:
      attestation.execution_state === "pending_override",
    action: attestation.decision.action,
    reason: attestation.decision.reason,
    attestation,
  };
}

async function clinicalReviewApprove(
  authorizationId: string,
  reviewerId: string,
  reviewerRole: string,
  clinicalReason: string
) {
  return client._request<{
    status: string;
    overrideId: string;
    resolution: { status: string; execution_fingerprint: string; signature: string };
  }>("/override", {
    method: "POST",
    body: JSON.stringify({
      executionId: authorizationId,
      approved: true,
      approvedBy: reviewerId,
      approverRole: reviewerRole,
      reason: clinicalReason,
    }),
  });
}

async function clinicalReviewDeny(
  authorizationId: string,
  reviewerId: string,
  reviewerRole: string,
  denialReason: string
) {
  return client._request<{
    status: string;
    executionId: string;
  }>("/override", {
    method: "POST",
    body: JSON.stringify({
      executionId: authorizationId,
      approved: false,
      approvedBy: reviewerId,
      approverRole: reviewerRole,
      reason: denialReason,
    }),
  });
}

// Example usage
async function main() {
  // Auto-approved: emergency
  const emergency = await requestPriorAuth("PA-2024-00341", {
    procedureCode: "27447",   // total knee replacement
    diagnosisCode: "M17.11", // primary osteoarthritis, right knee
    memberPlanTier: "standard",
    providerNetwork: "in_network",
    estimatedCost: 30000,
    urgency: "emergency",
    priorAuthCount: 0,
    treatmentDuration: 3,
  });
  console.log(emergency.action);   // "approve" — emergency overrides cost threshold
  console.log(emergency.approved); // true

  // Auto-approved: routine, in-network, low cost
  const routine = await requestPriorAuth("PA-2024-00342", {
    procedureCode: "71046",   // chest X-ray
    diagnosisCode: "J18.9",  // pneumonia
    memberPlanTier: "premium",
    providerNetwork: "in_network",
    estimatedCost: 450,
    urgency: "routine",
    priorAuthCount: 1,
    treatmentDuration: 1,
  });
  console.log(routine.action);   // "approve"
  console.log(routine.approved); // true

  // Clinical review: out-of-network
  const outOfNetwork = await requestPriorAuth("PA-2024-00343", {
    procedureCode: "27447",
    diagnosisCode: "M17.11",
    memberPlanTier: "standard",
    providerNetwork: "out_of_network",
    estimatedCost: 35000,
    urgency: "routine",
    priorAuthCount: 0,
    treatmentDuration: 3,
  });
  console.log(outOfNetwork.action);               // "clinical_review"
  console.log(outOfNetwork.pendingClinicalReview); // true

  // Medical director approves out-of-network case
  if (outOfNetwork.pendingClinicalReview) {
    const approved = await clinicalReviewApprove(
      "PA-2024-00343",
      "md-dr-patricia-osei",
      "medical_director",
      "No in-network specialist available within 50 miles. " +
      "Out-of-network approved at in-network benefit level."
    );
    console.log(approved.status);     // "approved"
    console.log(approved.overrideId); // override record ID
  }
}

main().catch(console.error);
```

***

## Expected results

| Input                                               | Expected `action` | `requires_override` |
| --------------------------------------------------- | ----------------- | ------------------- |
| `urgency: "emergency"`                              | `approve`         | `false`             |
| `providerNetwork: "in_network", estimatedCost: 450` | `approve`         | `false`             |
| `providerNetwork: "out_of_network"`                 | `clinical_review` | `true`              |
| `estimatedCost: 30000`                              | `clinical_review` | `true`              |
| `priorAuthCount: 7`                                 | `clinical_review` | `true`              |

***

## Audit and compliance

The governance attestation for each PA decision serves as the authorization record for:

* Appeals and grievances (the signed attestation proves what policy governed the decision)
* Utilization management reporting
* State insurance department audits (provide the attestation + public key; they verify independently)

```typescript theme={null}
// Retrieve authorization record for an appeal
const record = await client.audit.decision("PA-2024-00343");

console.log(record.policy_id);           // "prior-auth"
console.log(record.policy_version);      // "1.0.0"
console.log(record.decision);            // "clinical_review"
console.log(record.execution_state);     // "completed" (after override resolved)
console.log(record.signature_verified);  // "verified"
console.log(record.executed_at);         // ISO timestamp of original decision
```

***

## Troubleshooting

**Emergency authorization still pending clinical review** The `urgency: "emergency"` rule must be the first rule in the policy (rules are evaluated in order; first match wins). Verify the emergency rule appears before the cost and network rules.

**Attestation verification failed** The server's public key may have changed since the attestation was produced, or the attestation was tampered with. Do not grant the authorization. Investigate before proceeding.

**"Pending override not found" on clinical review** The `authorizationId` must match exactly between the execute call and the override call. Verify you are not adding or removing prefixes between calls.