Group Scheme Service
Manages employer group schemes, employee rosters, and bulk enrollment — the entry point for employer-sponsored coverage.
Overview
The Group Scheme Service enables employer groups to manage their employee health insurance programs. An employer creates a Scheme that defines the coverage configuration for their workforce. Members (employees and their dependants) are added to the scheme roster. When the employer wants to enroll a large cohort at once, they submit a bulk enrollment job which asynchronously enrolls each member via the Enrollment service.
The service enforces an employer-admin Keycloak role requirement on all its endpoints — only authenticated employer administrators can manage schemes and initiate bulk enrollments.
Bulk enrollment jobs run asynchronously. The employer submits a job with a list of members, receives a job locator, and polls the status endpoint until the job completes. Individual member enrollment calls are made to the Enrollment service for each entry in the job.
Responsibilities
- Create and manage employer group schemes
- Maintain employee/member rosters per scheme (add, remove, list members)
- Accept and execute bulk enrollment jobs asynchronously
- Coordinate with Enrollment service to create individual policies per member
- Report bulk enrollment job status and per-member results
Database
Schema: group_scheme
| Table | Purpose |
|---|---|
schemes | Employer group scheme records with coverage configuration |
scheme_members | Roster of members (party locators) enrolled in each scheme |
bulk_enrollment_jobs | Bulk enrollment job records with status and per-member results |
API Routes
All routes require JWT authentication and the employer-admin Keycloak role.
| Method | Path | Auth | Description |
|---|---|---|---|
POST | /api/v1/schemes | JWT + employer-admin | Create a new group scheme |
GET | /api/v1/schemes | JWT + employer-admin | List schemes for the employer |
GET | /api/v1/schemes/{locator} | JWT + employer-admin | Get scheme by locator |
PATCH | /api/v1/schemes/{locator} | JWT + employer-admin | Update scheme configuration |
POST | /api/v1/schemes/{locator}/members | JWT + employer-admin | Add a member to the scheme roster |
DELETE | /api/v1/schemes/{locator}/members/{memberPartyLocator} | JWT + employer-admin | Remove a member from the roster |
GET | /api/v1/schemes/{locator}/members | JWT + employer-admin | List members on the roster |
POST | /api/v1/schemes/{locator}/bulk-enrollments | JWT + employer-admin | Start a bulk enrollment job |
GET | /api/v1/bulk-enrollments/{jobLocator}/status | JWT + employer-admin | Poll bulk enrollment job status |
Events
Publishes
The Group Scheme Service does not publish Kafka events directly.
Consumes
The Group Scheme Service does not consume Kafka events.
Dependencies
| Service | How used |
|---|---|
| Enrollment | Called per-member to create quotes and policies during bulk enrollment jobs |
| Billing | Fetches billing aggregates for employer group billing summaries |
| Eligibility | Fetches coverage roster for employer eligibility reporting |
Key Design Decisions
Role-based access at the handler level: The employer-admin role is enforced by a chi middleware that inspects JWT claims. This means any missing or incorrect role in the Keycloak token results in a 403 at the HTTP layer before any business logic runs.
Asynchronous bulk enrollment: Bulk enrollment jobs are non-blocking. The employer receives a job locator immediately and polls for status. This prevents HTTP timeout issues when enrolling large employee cohorts and allows partial success (some members succeed, some fail) to be reported without rolling back the entire batch.