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

# Clearinghouse Administration Guide

> Version: 1.0.0 Last Updated: 2026-02-23 Clearinghouse Integration

**Version:** 1.0.0\
**Last Updated:** 2026-02-23\
**Spec:** PM-15 Clearinghouse Integration

***

## Overview

The Clearinghouse module enables your organization to connect to ANSI X12 clearinghouses for electronic claims submission (837P/I), remittance retrieval (835), eligibility verification (270/271), claim status inquiries (276/277), and prior authorization requests (278).

**Phase 1** provides configuration management, batch tracking, transaction logging, and payer enrollment. Actual clearinghouse transport (Waystar REST/SFTP) is planned for **Phase 2**.

***

## Prerequisites

* **Organization Admin** or **Billing Manager** role with `pm.clearinghouse.admin` permission
* Active payer records in PM-02 (Insurance & Eligibility)
* Clearinghouse vendor contract (e.g., Waystar) with credentials

***

## 1. Configuring a Clearinghouse Connection

### Navigate

**Practice Management → Clearinghouse → Configurations**

### Add New Configuration

1. Click **Add Configuration**

2. Fill required fields:
   * **Clearinghouse Name** — Display name (e.g., "Waystar Production")
   * **Provider** — Select from supported providers (currently: Waystar)
   * **Connection Type** — `API` or `SFTP`
   * **Sender ID** — Your organization's sender identifier
   * **Receiver ID** — Clearinghouse receiver identifier

3. **For API connections:**
   * **API Endpoint** — Full URL provided by clearinghouse
   * **Credentials Vault Ref** — Vault reference for API key/token (e.g., `vault://waystar/api-key`)

4. **For SFTP connections:**
   * **Host** — SFTP server hostname
   * **Port** — SFTP port (default: 22)
   * **Submission Path** — Remote directory for outbound files
   * **Retrieval Path** — Remote directory for inbound files (835s)
   * **Username Vault Ref** — Vault reference for SFTP username
   * **Credentials Vault Ref** — Vault reference for SFTP password/key

5. Click **Save**

### Vault References

Credentials are **never stored in the database**. Instead, the configuration stores a vault reference string that is resolved at runtime by the edge function.

**Format:** `vault://{provider}/{key-name}`

**Examples:**

* `vault://waystar/api-key` — Waystar API key
* `vault://waystar/sftp-password` — Waystar SFTP password

To add credentials, go to **Settings → Cloud → Secrets** and add the secret with the corresponding name.

***

## 2. Payer Enrollment

Before submitting claims through a clearinghouse, each payer must be enrolled.

### Navigate

**Practice Management → Clearinghouse → Enrollments**

### Add Enrollment

1. Click **Add Enrollment**
2. Select:
   * **Clearinghouse** — The configuration to enroll with
   * **Payer** — The insurance payer
   * **Transaction Types** — Which X12 transactions are enabled (837P, 837I, 835, 270/271, etc.)
3. Set **Enrollment Status** (pending, active, suspended, terminated)
4. Fill optional dates: **Enrolled Date**, **Effective Date**, **Termination Date**
5. Click **Save**

### Enrollment Statuses

| Status       | Description                            |
| ------------ | -------------------------------------- |
| `pending`    | Application submitted to clearinghouse |
| `active`     | Enrolled and ready for transactions    |
| `suspended`  | Temporarily disabled                   |
| `terminated` | No longer enrolled                     |

***

## 3. Transaction Batches

Batches group related X12 transactions for submission or retrieval.

### Navigate

**Practice Management → Clearinghouse → Batches**

### Batch Lifecycle

| Status      | Description                           |
| ----------- | ------------------------------------- |
| `pending`   | Batch created, awaiting submission    |
| `submitted` | Sent to clearinghouse                 |
| `accepted`  | Acknowledged by clearinghouse (999)   |
| `rejected`  | Rejected by clearinghouse (999/277CA) |
| `processed` | Fully processed (835 posted, etc.)    |
| `error`     | System error during processing        |

### Viewing Batch Details

Click any batch row to see:

* Transaction type, direction, record count
* Submission timestamp and response data
* Error details (if rejected)
* File name and size

***

## 4. Transaction Log

The transaction log is an **append-only audit trail** of all clearinghouse interactions.

### Navigate

**Practice Management → Clearinghouse → Transactions**

### Key Fields

* **Trace Number** — Unique identifier for tracking
* **Transaction Type** — X12 type (837P, 835, etc.)
* **Direction** — Inbound or outbound
* **Status** — Current processing status
* **Claim ID** — Associated claim (if applicable)

**Note:** Transaction log entries cannot be edited or deleted. This ensures audit integrity for HIPAA compliance.

***

## 5. Security Considerations

### Credential Storage

* All credentials use vault references — never stored in the database
* Edge functions resolve vault refs at runtime
* Rotate credentials regularly through your vault provider

### Audit Trail

* All configuration changes are tracked via `created_by`/`updated_by`
* Transaction log is immutable (append-only, no UPDATE/DELETE)
* Batch status changes are timestamped

### PHI Protection

* X12 transactions contain PHI (patient demographics, diagnoses)
* All transport uses TLS encryption
* Log entries do not store claim content — only trace numbers and status

### Multi-Tenant Isolation

* All clearinghouse data is scoped by `organization_id`
* Row-Level Security (RLS) with `FORCE` prevents cross-tenant access
* DELETE operations restricted to `org_admin` role

***

## 6. Troubleshooting

### Common Issues

| Issue                             | Solution                                                           |
| --------------------------------- | ------------------------------------------------------------------ |
| "Configuration validation failed" | Check that all required fields are filled for your connection type |
| Batch stuck in "submitted"        | Phase 1 stub — no transport yet. Will resolve in Phase 2           |
| Cannot delete configuration       | Only `org_admin` can delete. Check your role assignment            |
| Enrollment not showing payer      | Ensure the payer exists in PM-02 with an active status             |

### Edge Function Logs

Check the `clearinghouse-batch-submit` function logs:
**Supabase Dashboard → Edge Functions → clearinghouse-batch-submit → Logs**

***

## 7. Phase 2 Roadmap

Phase 2 will implement:

* Live Waystar REST API connectivity
* SFTP file transfer for 837P/I submission and 835 retrieval
* Real-time eligibility checks (270/271)
* Claim status inquiries (276/277)
* Prior authorization requests (278)
* Automated ERA processing and payment posting

***

## References

* [PM-15 Spec](../../specs/pm/specs/PM-15-clearinghouse-integration.md)
* [X12 EDI Technical Design](../architecture/standards/X12-EDI-TECHNICAL-DESIGN.md)
* [PM-15 Integration Doc](../architecture/integrations/clearinghouse-integration-integration.md)