Onboarding a payer + program config

Outcome

A payer/state combination is onboarded for a tenant with the right program config (filing windows, auth workflow, NPI type, group caps), contract, and aliases.

Prerequisites

• config.read to browse, config.update to mutate.
• Master payer row already exists (master payer creation isn't in this UI's scope — use Configure a new payer).

Find or verify the payer

1. Navigate to /admin/payers. Filter by state + payer type + text search.

2. If the payer is missing, the master row still has to be seeded — master-payer creation is not in this UI's scope. Open a ticket and request a seed row before proceeding.

Add a program config

Program configs live in tenant config.payer_program_config and drive claim-scrub behavior: filing windows, auth workflow, institutional billing period, group caps, no-show rules.

1. Open the payer → Programs tab → New config.

2. Binding — supply the canonical program UUID (pulled from the programs admin surface — not editable on this form). Pick an effective from date.

3. Submission — claim type (P/I), submission method (EDI today for most payers; PORTAL / PAPER / API available), and billing NPI type (GROUP default; INDIVIDUAL or FACILITY per contract).

4. Filing — timely filing days. Leave blank to inherit the canonical program's default.

5. Authorization — auth workflow:

   Workflow	Required additional field	Behavior
   EDI_278	—	Outbound 278s flow through AuthRequestService.
   PORTAL	authPortalUrl (inline-required field)	Auth UI links out to the URL.
   MANUAL	—	Authorizations are entered by hand; no automation runs.

6. Institutional — billing period (WEEKLY / MONTHLY / SPAN). Only consumed for institutional claims.

7. Limits — max units per day / week and max group size. Null means no UI-enforced cap.

8. No-show — if "Allows no-show billing" is on, a procedure code is required. Pick at least one attendance status (ABSENT / LATE) to bill.

9. Save. The grid refreshes; changes are live for subsequent claim scrubs without a restart.

Edit vs. new: the form disables canonicalProgramId and effectiveFrom in edit mode — those two form the compound key. To roll out a new filing window, create a new config row with a later effectiveFrom.

Add a contract

1. Open the payer → Contracts tab → New contract.

2. Pick a billing entity (or leave "No billing entity" to attach the contract at the payer level). The dropdown pulls from /admin/billing-entities.

3. Enter the contract number. Uniqueness is enforced per (payer, billing_entity) — server returns 409 on collision.

4. Set effective from / to and optional notes. Save.

Once the contract exists, a fee schedule can be linked back via /admin/fee-schedules/:id → Contract ID field. The cross-payer trigger enforces referential integrity at save.

Manage aliases

Aliases live in rcm_master.payer_alias and let inbound ingestion map external payer names (e.g., "UHC Behavioral", "United Behavioral Health") to a single canonical payer row.

1. Open the payer → Aliases tab → Add alias. Free-text alias name + optional context tag (e.g. BEHAVIORAL, INGEST_FEED, state abbreviation).

2. To retire an alias, click the × icon. Aliases are soft-deleted (is_active=false) so historical inbound lookups still resolve.

Audit trail

Every mutating route emits a structured log line:

Event	When
admin.payer.program-config.created	POST succeeds
admin.payer.program-config.updated	PATCH succeeds
admin.payer.contract.created	POST succeeds
admin.payer.contract.updated	PATCH succeeds
admin.payer.alias.created	POST succeeds
admin.payer.alias.deactivated	DELETE succeeds

Each line carries orgId, userId, entityId, and the key changed fields. Grep journalctl -u rcm-core (or the log aggregator) when reconciling tenant-onboarding tickets.

Validation

Check	Expected
New PPC row in config.payer_program_config	Visible in detail tab
Auth workflow honored on submit	Per Auth workflow + 278 lifecycle
Contract uniqueness violation	409 returned
Aliases soft-deleted, not hard-deleted	is_active=false row remains

Cross-references

• Configure a new payer for master setup.
• Commercial payer onboarding for bulk seeds.
• Authorization workflow + 278 lifecycle UI for runtime auth behavior.

Next

4.7 — Modifier rules editing & simulation