Skip to main content

Onboarding program settings, payers and contracts

Outcome​

Every program the tenant bills has a program setting (filing window, auth workflow, NPI type, group caps) that every payer follows, payer-specific settings only where a payer bills the program differently, and each payer has its 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 setting​

Program settings live in tenant config.program_config, keyed by program (program_id, a rcm_master.program row) with an optional payer (payer_id). They drive claim-scrub behavior: whether the program accepts claims, filing windows, auth workflow, institutional billing period, group caps, no-show rules.

  • payer_id NULL — the program setting, followed by every payer of the program.
  • payer_id set — a payer-specific setting. It replaces the program setting for that payer on the days it is in force; it does not merge with it.

There are no payer program enrollments any more (#5990): rates and code rules are resolved from the program, the facility's state and the payer. A claim whose program has no setting in force on its first date of service, or whose setting does not accept claims, is blocked at scrub with PROGRAM_CONFIG_MISSING. Configure the program settings before the first scrub.

  1. Open Configuration → Programs (/admin/programs) → New program setting. For a payer-specific setting, either pick the payer there or open the payer → Programs tab → New payer-specific setting (payer fixed).

  2. Binding — leave Payer (optional) empty for the program setting; pick the Program by name from the list. Pick an effective from date — the tenant's first date of service, or earlier to back-bill.

  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 fall back to the payer's submission-capability TFD.

  5. Authorization — auth workflow:

    WorkflowRequired additional fieldBehavior
    EDI_278—Outbound 278s flow through AuthRequestService.
    PORTALauthPortalUrl (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 the program and the payer in edit mode. effectiveFrom stays editable so a setting can be backdated to back-bill older claims; a date before today needs a reason (audited). Two settings for the same program and payer (or both with no payer) cannot start on the same day. To roll out a new filing window, create a new setting with a later effectiveFrom.

A payer-specific setting replaces the whole program setting for that payer, so fill in every field, not only the ones that differ.

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:

EventWhen
admin.payer.program-config.createdPOST succeeds
admin.payer.program-config.updatedPATCH succeeds
admin.payer.contract.createdPOST succeeds
admin.payer.contract.updatedPATCH succeeds
admin.payer.alias.createdPOST succeeds
admin.payer.alias.deactivatedDELETE 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​

CheckExpected
One config.program_config row with payer_id NULL per program billedListed under Program setting · all payers on Configuration → Programs
Payer-specific rowsListed on Configuration → Programs and on the payer's Programs tab
Getting Started B5/B6 checksNo program on active coverage without a setting
Auth workflow honored on submitPer Auth workflow + 278 lifecycle
Contract uniqueness violation409 returned
Aliases soft-deleted, not hard-deletedis_active=false row remains

Cross-references​

Next​

4.7 — Modifier rules editing & simulation