Group Schemes

The group-scheme service runs employer group cover: the arrangement that links an employer to a cohort of member policies, and the bulk machinery to enrol them.

Field reference: full columns, types and nullability live in the catalog: glossary terms Scheme, SchemeMember, BulkEnrollmentJob. This page is the narrative.

Scheme and members

• Scheme is the employer arrangement: a unique code, a name, the sponsoring employer (employer_party_locator), and a status (free text, default ACTIVE). It scopes the employer portal to the right member population.
• SchemeMember associates a covered member with the scheme: member_party_locator, the policy_locator once enrolled, and a membership status. At most one membership per (scheme, member) (a UNIQUE constraint). The billing account for the whole scheme rolls up to the employer; see Members & Parties.

Bulk enrollment

BulkEnrollmentJob processes a CSV/API upload of employees asynchronously: it tracks total / processed / failed_count, with per-row failures stored in an errors JSONB array on the job (status defaults to PENDING). This enables partial recovery: fix the failed rows and resubmit without re-running the whole batch.

Invariants

• Scheme.code and Scheme.locator are each unique; at most one SchemeMember per (scheme, member).
• A bulk job's errors array captures every failed row; successful rows yield a SchemeMember (and policy).

Caveats

• Scheme.status and SchemeMember.status are free TEXT (no DB CHECK); the OpenAPI schema documents a small enum, but it is not DB- or service-enforced.
• All party/policy references are locator (text), not UUID FKs.
• BulkEnrollmentJobError, BulkMember, EligibilityRoster and BillingAggregate appear in the model but are aspirational: errors live in the job's JSONB array, bulk rows are transient upload input, and the roster/aggregate are computed on demand (no tables).