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

# Managed Care Authorization Tracking — Integration Documentation

> Spec: specs/pm/specs/PM-47-managed-care-authorization-tracking.md Status: 📋 Planned Last Updated: 2026-04-07

**Spec:** `specs/pm/specs/PM-47-managed-care-authorization-tracking.md`\
**Status:** 📋 Planned\
**Last Updated:** 2026-04-07

***

## Overview

PM-47 provides managed care authorization lifecycle tracking, expiration alerting, auth-to-claim validation, and auth denial appeal workflows for behavioral health organizations. It extends PM-10 (Prior Authorization Management) with ongoing MCO-specific tracking capabilities.

***

## Integration Points

### Platform Foundation Dependencies

| Dependency                    | Type                                        | Description                                                       |
| ----------------------------- | ------------------------------------------- | ----------------------------------------------------------------- |
| PF-01 (Organizations & Sites) | Direct                                      | Organization and site context for multi-tenant auth tracking      |
| PF-02 (RBAC)                  | Direct                                      | Permission checks for auth management actions                     |
| PF-10 (Notifications)         | Platform Layer (`@/platform/notifications`) | Auth expiration alerts and review deadline reminders              |
| PF-96 (Jurisdiction Profiles) | Platform Layer (`@/platform/jurisdiction`)  | Payer-specific filing deadlines, review intervals, appeal windows |

### Same-Core Dependencies

| Dependency                       | Type                                    | Description                                                                                                                                                                           |
| -------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PM-10 (Prior Authorization)      | Data (logical linkage: `prior_auth_id`) | PM-47 `pm_managed_care_authorizations.prior_auth_id` provides logical linkage to PM-10 `pm_prior_authorizations.id`. PM-10 owns PA request/approval; PM-47 owns ongoing MCO tracking. |
| PM-08 (Claims Submission)        | Event / Validation Gate                 | PM-47 provides pre-submission auth-to-claim validation. Consumes `pm.claim.posted` to increment `used_units`.                                                                         |
| PM-29 (Claims Denial Management) | Boundary                                | PM-29 owns claim denials (post-submission); PM-47 owns auth denials (pre-submission). Distinct workflows, actors, and timelines.                                                      |

### Cross-Core References

| Core                           | Type           | Description                                                                                                                       |
| ------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| CL-36 (Clinical Documentation) | UUID reference | Clinical docs referenced by ID in concurrent review submissions and appeal justifications. No FK, no schema changes to CL tables. |

***

## Event Contracts

### Events Published

| Event Name                  | Publisher | Subscribers                                       | Payload                                                                                        | Status     |
| --------------------------- | --------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------- |
| `pm.auth.expiring`          | PM-47     | PM (dashboard refresh), CL (clinical review prep) | `{ authorization_id, patient_id, payer_id, expiration_date, days_remaining, organization_id }` | 📝 Planned |
| `pm.auth.validation_failed` | PM-47     | PM-08 (claim submission gate)                     | `{ claim_id, failed_lines: [{ line_number, reason }], organization_id }`                       | 📝 Planned |

### Events Consumed

| Event Name        | Publisher | Description                                                         |
| ----------------- | --------- | ------------------------------------------------------------------- |
| `pm.claim.posted` | PM-08     | Increment `used_units` on matching authorization when claim is paid |

***

## API Contracts

### Edge Functions

| Function                    | Method               | Purpose                                            | Auth         |
| --------------------------- | -------------------- | -------------------------------------------------- | ------------ |
| `pm-auth-expiration-alerts` | Cron (daily 6:00 AM) | Check for expiring auths, send PF-10 notifications | Service role |
| `pm-auth-claim-validation`  | POST                 | Validate claim lines against active auths          | JWT (user)   |

### Validation API (pm-auth-claim-validation)

**Request:**

```typescript theme={null}
{
  claim_id: string;
  claim_lines: Array<{
    line_number: number;
    date_of_service: string;
    units: number;
    service_type: string;
  }>;
  organization_id: string;
}
```

**Response:**

```typescript theme={null}
{
  valid: boolean;
  results: Array<{
    line_number: number;
    status: 'pass' | 'fail';
    reason?: string;
    authorization_id?: string;
  }>;
}
```

***

## Platform Layer Usage

| Layer         | Import                     | Usage                                                   |
| ------------- | -------------------------- | ------------------------------------------------------- |
| Notifications | `@/platform/notifications` | Auth expiration alerts, review reminders                |
| Jurisdiction  | `@/platform/jurisdiction`  | `useJurisdictionProfile()` for payer-specific deadlines |
| Permissions   | `@/platform/permissions`   | `useHasPermission()` for auth management actions        |

***

## Permission Keys

| Key                             | Purpose                                   |
| ------------------------------- | ----------------------------------------- |
| `pm.managed_care_auth.view`     | View authorization list and details       |
| `pm.managed_care_auth.create`   | Create new authorizations                 |
| `pm.managed_care_auth.edit`     | Edit authorization records                |
| `pm.managed_care_auth.validate` | Run auth-to-claim validation              |
| `pm.managed_care_auth.override` | Override validation failures (supervisor) |
| `pm.auth_review.manage`         | Manage concurrent reviews                 |
| `pm.auth_appeal.manage`         | Manage auth denial appeals                |

***

## Data Flow Diagram

```
PM-10 (PA Request)
  └── pm_prior_authorizations (approved)
       └── PM-47: pm_managed_care_authorizations (prior_auth_id FK)
            ├── Dashboard: expiration countdown, remaining units
            ├── Alerts: PF-10 notifications at 14/7/3/1 days
            ├── Concurrent reviews: pm_auth_concurrent_reviews
            ├── Retro-auth: structured workflow
            ├── Auth denial appeals: pm_auth_denial_appeals
            └── Validation gate → PM-08 claim submission
                 └── pm.claim.posted → used_units increment
```

***

## Validation Checklist

* [x] All integration points documented
* [x] Event contracts have payload schemas
* [x] API contracts have request/response schemas
* [x] Platform layer usage documented
* [x] Permission keys listed
* [ ] Integration tests planned (see spec Testing Strategy)

***

**References:**

* Spec: `specs/pm/specs/PM-47-managed-care-authorization-tracking.md`
* PM-10 Integration: `docs/architecture/integrations/PM-10-prior-authorization-management-INTEGRATION.md`
* PM-08 Integration: `docs/architecture/integrations/PM-08-claims-management-submission-INTEGRATION.md`
* PM-29 Integration: `docs/architecture/integrations/PM-29-claims-denial-management-appeals-INTEGRATION.md`
* PF-96 Integration: `docs/architecture/integrations/PF-96-medicaid-state-compliance-configuration-INTEGRATION.md`