File ingestion: eligibility upload, schema review

Eligibility files are how payers tell you who is eligible for the coming period. Rendum supports CSV, XLSX, and EDI 834 formats. The Layer 1 ingestion pipeline parses the file, resolves each row against your member roster, and writes EligibilityEvent rows that drive the rules engine's billable-day decisions.

Uploading a file

From the Eligibility screen, click Upload File on the target payer. Drag-and-drop the file or use the file picker. Accepted formats:

• CSV up to 100 MB
• XLSX up to 100 MB
• EDI 834 (text or zipped)

Each upload is queued on the data-import BullMQ queue and processed asynchronously. The screen shows live progress.

Schema detection (first upload per payer)

On the first upload for a payer, Rendum runs schema detection: the parser inspects the columns and proposes a mapping to the canonical fields the rules engine expects (member_id, member_mbi, effective_date, termination_date, plan_code, etc.).

You can override any column mapping inline, mark unrecognized columns as "ignore", or supply the canonical name for a custom column. When you save, the mapping is persisted as a PayerFileSchema row and reused on every subsequent upload for the same payer.

If a future upload arrives with a schema that differs from the persisted one (new columns, renamed columns), the platform raises an exception and pauses the ingestion until you reconcile.

Member resolution

For each row in the file, Layer 1 attempts to resolve the asserted member to your roster. The resolution order:

1. Match by member_mbi (preferred — MBI is the most stable identifier)
2. Match by member_id (payer-assigned)
3. Fall through to creating a new member if neither match exists

If a row resolves to a member whose state machine doesn't permit the asserted transition, the parser raises an exception (see Chapter 5).

State machine

Each member-per-payer has a state: Active, Suspended, Terminated, or Pending. Layer 1 enforces the legal transitions; illegal transitions raise exceptions rather than silently flipping state. Edge cases handled:

• Late-arriving file says "this member terminated last month" → retroactive termination via the retroactive window.
• Duplicate rows in the same file → de-duped; second row noted in the audit row.
• A member appears for one payer this month and a different payer next month → both relationships preserved; billing logic resolves which one bills.

Service-delivery files (Layer 1b)

Payers whose rule sets requiresServiceDelivery: true also need service-delivery files. When Layer 2 runs for these payers, it reconciles: every eligible member needs at least one service event in the billing period or the decision becomes NOT_BILLED_NO_SERVICE.

Dropped-member detection

If a previously-active member is absent from a new file, Layer 1's dropped-member detector raises an exception. Common reasons: the payer rolled them off, a parsing glitch, or the file is a partial roster.

Audit footprint

Every file produces audit rows:

• IMPORT_JOB_QUEUED — when the upload lands
• IMPORT_JOB_STARTED — when the worker picks it up
• IMPORT_JOB_COMPLETED — when parsing finishes, with summary counts
• MEMBER_STATE_TRANSITION — for each row that changed a member's state
• EXCEPTION_RAISED — for each parser exception

Permissions

• OWNER, ADMIN, BILLING_MANAGER, OPERATIONS can upload eligibility / service files.
• All roles can view file history.
• Schema-mapping decisions require ADMIN or higher.