Clearinghouse Administration Guide

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.

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

---

​

3. Transaction Batches

Batches group related X12 transactions for submission or retrieval.

​

Navigate

Practice Management → Clearinghouse → Batches

​

Batch Lifecycle

​

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

​

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
• X12 EDI Technical Design
• PM-15 Integration Doc