> ## 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.

# Provider Credentialing & Enrollment Verification — Integration

> Version: 1.0.0 Status: \U0001F4DD Planned Last Updated: 2026-02-23 Provider Credentialing & Enrollment Verification Constitution Reference: Section 1.3 (In…

**Version:** 1.0.0\
**Status:** 📝 Planned\
**Last Updated:** 2026-02-23\
**Spec:** [PM-17 Provider Credentialing & Enrollment Verification](../../../specs/pm/specs/PM-17-provider-credentialing-enrollment-verification.md)\
**Constitution Reference:** Section 1.3 (Integration Patterns), Section 2.1 (Integration points documented in `/docs/architecture/integrations/`)

***

## Overview

PM-17 provides provider payer-enrollment tracking, NPI/taxonomy validation, re-credentialing deadlines and alerts, and claim-scrub integration for enrollment verification. It consumes HR provider/credential context via the Platform Integration Layer (no direct PM→HR imports). Integration points: PM-08 (claim scrub), PM-15 (clearinghouse readiness), HR (provider identity/credential context), PF-10 (alerts).

## Quick Reference

| I need to…                       | Pattern                                               | Location                                       |
| -------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
| Validate NPI/taxonomy state      | `pm.credentialing.validate` permission-gated workflow | [Permission Keys](#permission-keys)            |
| Gate claims by enrollment status | PM-08 consumes PM-17 enrollment state                 | [Integration Points](#integration-points)      |
| Verify submission readiness      | PM-15 checks enrollment/validation outputs            | [API / Event Contracts](#api--event-contracts) |

## Decision Tree

1. Is provider enrollment status eligible for payer submission?
   * `enrolled` → proceed.
   * `pending`/`denied`/`inactive` → enforce PM-08/PM-15 hold or override policy.
2. Is NPI/credential validation current?
   * Yes → continue.
   * No → run validation flow and re-check before submission.
3. Is re-credentialing deadline approaching?
   * Yes → trigger PF-10 alerts and assign follow-up.

## Pattern Library

* **Platform integration layer pattern:** consume HR provider context via contracts only.
* **Enrollment-state gating pattern:** use PM-17 status as hard/soft stop in PM-08/PM-15 workflows.
* **Deadline-alert pattern:** route expiring enrollment events/notifications through PF-10.

## Common Mistakes

| Mistake                                       | Impact                     | Fix                                                   |
| --------------------------------------------- | -------------------------- | ----------------------------------------------------- |
| Missing org scope in enrollment queries       | Cross-tenant leakage risk  | Enforce `organization_id` in queries and RLS          |
| Using view/manage permissions interchangeably | Unauthorized modifications | Separate action permissions by role and operation     |
| Skipping NPI active-date validation           | Claim rejection risk       | Require validation checks before submission workflows |

## Pre-Flight Checklist

* [ ] `organization_id` scoping and RLS policies validated on PM-17 tables.
* [ ] Permission keys seeded and mapped for view/manage/validate/override.
* [ ] PM-08 and PM-15 consuming contracts verified against PM-17 status model.
* [ ] Re-credentialing alert flow validated through PF-10.

***

## Integration Points

| Dependency | Pattern                    | Purpose                                                                                 |
| ---------- | -------------------------- | --------------------------------------------------------------------------------------- |
| **PM-08**  | Data / API                 | Claim scrub enrollment verification rules; consume enrollment status as hard/soft stop. |
| **PM-15**  | Data / API                 | Clearinghouse and payer-submission readiness checks.                                    |
| **HR**     | Platform Integration Layer | Provider identity, license/credential context (contract-based; no direct core import).  |
| **PF-10**  | Platform                   | Alerts for expiring enrollments and re-credential windows.                              |

***

## API / Event Contracts

### Inbound (consumed by PM-17)

* **Provider/credential context:** Consumed via Platform Integration Layer contract from HR (provider identity, credential attributes). Request/response schema TBD in HR–PM integration contract.
* **PM-08:** Reads enrollment status for claim scrub (query or shared types). Contract: enrollment status per provider/payer for given claim context.

### Outbound (provided by PM-17)

* **Enrollment status:** PM-08 and PM-15 consume enrollment state (enrolled/pending/denied/inactive) and validation results for scrub and submission readiness.
* **Alerts:** PF-10 receives enrollment/re-credential deadline events for alert generation (event or API TBD).

### Planned Events (Deferred)

**`pm_enrollment_expiring`** — Planned but deferred from v1. V1 uses direct PF-10 notification insert for re-credentialing alerts. Domain event will be added if downstream consumers (PM-08 automation, GR compliance) need to subscribe.

***

## Security & Tenant Isolation

* All PM-17 tables are scoped by `organization_id`; RLS and SECURITY DEFINER helpers enforce isolation per constitution §5.
* Provider and enrollment data are operationally sensitive; access via permission keys below.
* No PHI sent to external AI; HR integration uses platform contract only.

### Permission Keys

| Key                         | Purpose                                            | Typical role assignments            |
| --------------------------- | -------------------------------------------------- | ----------------------------------- |
| `pm.credentialing.view`     | View enrollment/credentialing data                 | org\_admin, billing\_manager, staff |
| `pm.credentialing.manage`   | Create/update enrollment and credentialing records | org\_admin, billing\_manager        |
| `pm.credentialing.validate` | Run validation (e.g. NPI/taxonomy checks)          | org\_admin, billing\_manager        |
| `pm.credentialing.override` | Override validation or restrictions                | org\_admin only                     |

**AHCCCS NPI:** `pm.credentialing.validate` and `pm.credentialing.manage` tie to AHCCCS NPI requirements: NPI must be present on submission forms and active for date of service.

***

## References

* [PM-17: Provider Credentialing & Enrollment Verification](../../../specs/pm/specs/PM-17-provider-credentialing-enrollment-verification.md)
* [PM-08: Claims Management & Submission](../../../specs/pm/specs/PM-08-claims-management-submission.md)
* [PM-15: Clearinghouse Integration](../../../specs/pm/specs/PM-15-clearinghouse-integration.md)
* [Platform Integration Layers](./PLATFORM_INTEGRATION_LAYERS.md)