Connect every employer to their benefits administrator

Problem. EN exposes a per-dependent tobaccoUseInformation.useTobacco field. Controller.php:486 assigns the parent employee's tobacco value to every dependent instead of reading each dependent's own value.

Fix. Read employees[].dependents[].demographics.tobaccoUseInformation.useTobacco per dependent. Spouse-tobacco rates differ from employee-tobacco rates for many carriers, so this matters.

Problem. Controller.php:424 hardcodes $useTypes = ['Medical']. Even though we successfully push Dental, Vision, STD, LTD, and Group Life plans to EN, when we pull census back, we silently drop every enrollment for those same lines. Brokers see employees from EN but not their dental/vision/life/disability elections.

Fix. Expand $useTypes to match the push side (Medical, Dental, Vision, STD, LTD, Group Life). The benefit-type loop and plan-storage logic in lines 494-549 should already handle additional types — verify by tracing each enrollment branch.

Problem. EN exposes employees[].companyStructureMapping with eligibilityClass, division, department, businessUnit, and officeLocation. None of these are read by Plansight. For a multi-class employer (different contributions / waiting periods / plan eligibility per class), this means we can't honor the broker's class-based logic.

Fix (medium lift). Capture eligibilityClass on the census record at minimum. Treat it as a typed enum — surface in the RFP UI and let the broker map EN classes to Plansight rate classes. Division/department can be string fields for display.

Problem. EN sends employmentInformation.benefitHireDate, jobTitle, benefitWorkState, and employmentCompensation.annualBenefitSalary. None are read in the census import.

What we'd gain. Hire date drives waiting-period logic and ACA eligibility — without it, brokers manually enter dates we already have. Salary enables salary-based plan modeling (multiple-of-earnings life, salary-banded disability). Work state matters for situs-state rating on multi-state employers.

Problem. EN sends benefitTier per enrollment (EmployeePlusFamily, EmployeePlusSpouse, etc.). Plansight ignores it and re-derives tier from dependent count. For most cases the answer matches, but EN's value is the source of truth for what the employee actually elected — re-deriving can disagree (e.g., if an employee has dependents but waived spouse coverage).

Fix. Store EN's benefitTier as the authoritative tier on the census enrollment. Use Plansight-derived tier as a sanity check, log when they differ.

Problem. EN sends employeeBenefit.effectiveDate + terminationDate (and dependent equivalents). Plansight stores neither. For renewal pulls or mid-year changes, we can't tell from the census whether someone is actively enrolled or aged off.

Fix. Capture both dates on the census enrollment. Treat enrollments where terminationDate < today as inactive.

Problem. EN's v3 notification spec exposes 16 plan-notification endpoints. Plansight's QuoteNotification.php (line 87–108) handles only 6 — Medical, Dental, Vision, Life, STD, LTD. The remaining 9 endpoints are valid push targets that Plansight ignores entirely; for these benefit lines the broker has to re-key everything in EN by hand after quoting in Plansight.

What's available. Counts come from scripts/extract-en-fields.py walking the v3 swagger; "fields" is the recursive count of leaf-level properties across the request body schema (the surface area we'd be choosing what to map from):

Phasing. Adding all nine at once is unnecessary. The ones brokers feel first are typically Voluntary Life, AD&D, Critical Illness, and Accident — those would unlock the most quoting → enrollment automation. Hospital Indemnity and Cancer are lower-volume; Voluntary STD/LTD overlap conceptually with the existing STD/LTD push.

What changed. Three current OpenAPI 3.0.1 specs were dropped into Employee Navigator Swagger/ on 2026-05-10:

• QuotingCompanyBenefitsNotificationApi_v3 (4).json — the push side. 16 plan-notification endpoints, 275 schema definitions. This is the document the previous audit was missing — the v1 census spec only described one endpoint.
• QuotingCompanyIntegrationRequestApi_v3_1 (2).json — the company-integration handshake (3 endpoints). Confirms current v3.1 is what Plansight calls.
• QuoteCensusApi v1.json — refreshed census spec (1 endpoint). Same shape as the August 2024 file; no breaking changes detected.

Audit script scripts/extract-en-fields.py walks all three specs and emits a coverage workbook (source/employee-navigator/EN_API_Coverage_<date>.xlsx) plus per-plan JSON dumps in source/employee-navigator/swagger-extracts/. Re-run after each refresh.

Still TBD. The example census response includes benefitEligibility.isEligible, period, and decision fields that still aren't in the formal OpenAPI schema. Plansight reads decision == 'Elected' — if EN tightens the schema, we'd silently break. Worth one email to EN partner support to either add these to the spec or confirm they'll stay forever.

The idea (not built). Today, when a broker starts a renewal RFP in Plansight, they have to either upload current-plan PDFs (which Plan Facts then parses) or hand-key the existing plan design. If EN already holds the same employer's current plan data, we may be able to pull plans + plan-design + current rates from EN and pre-populate the "current plans" side of the renewal automatically — bypassing the PDF dance for employers that are already on EN.

What's documented today. Updated 2026-05-10: we now have all three current EN specs on file (Benefits Notification v3, Integration Request v3.1, Quote Census v1). All three are push-only or one-shot pull — none of them expose GET plans or GET rates by company. So this gap is still open: pulling existing plan design + current rates from EN requires a partner API surface we still haven't seen. The shape we'd need would be roughly the inverse of the v3 notification request (read instead of write).

If feasible, what we'd gain. A "Connect EN → import current plans" button on renewal kickoff that eliminates 80% of the data-entry work for any employer already on EN. Better-than-Plan-Facts accuracy for those employers, since EN's plan data is the source of truth for what's actually being administered.

What changed. Plansight's dental plantype now has category-level summary fields under Schedule of Benefits: BenefitSchedPreventiveI (Type I), BenefitSchedBasicII (Type II), Type III (Major), and Type IV (Orthodontia). These are new — before, we only had the individual procedure-level fields (Exams, Cleanings, Basic Filling, Crowns, Dentures, Implants, Periodontics, Orthodontics, etc.), which already flow into EN's service-type fields (OralExaminations, CleaningsAdult/CleaningsChildren, Fillings, Crowns, etc.). Brokers were already filling those individual benefits in — they just rolled up implicitly under each category.

The gap. The new Type I–IV summary fields in config/plantypeFiles/dental.php aren't yet wired into the EN push the way the individual procedures are. Today their integrations.employeeNavigator config either points back at one of the same procedure-level EN attributes (e.g. BenefitSchedPreventiveI → OralExaminations) or is missing entirely (Type III, Type IV). That means the category-level value the broker enters at the top of the dental Schedule of Benefits doesn't actually land in EN as a Schedule-of-Benefits roll-up — it overwrites a single procedure on EN's side, or gets dropped.

What to do. Update the dental EN integration so each Type I–IV field pushes to the correct EN Schedule of Benefits roll-up rather than overwriting individual procedure values. Confirm the corresponding EN attribute names with the broader partner API spec (Edie's pending request) before wiring — we want the roll-ups to coexist cleanly with the individual procedure fields, not collide with them.

The opportunity. Every time a broker pulls an EN census today, the raw response is parsed into people rows and then garbage-collected. There's no persistent record of "what EN said the census was on date X" — if an enrollment dispute comes up later, the broker has to re-pull and hope nothing changed in the interim.

The fix. After each successful census pull, drop two snapshot files into a per-group EN Census Snapshots folder under the group's documents (already on S3 via App\Helpers\S3GroupFile): the raw JSON response and a flat CSV of all employees + dependents. Filename pattern: EN_Census_<YYYY-MM-DD>_<HHMM>.{json,csv}. Side-effect of the existing pull, wrapped in try/catch so a snapshot failure can never break the broker's census pull.

Why it's a quick win. ~50 lines, one file, one commit. No schema changes. No UX to design. No migration. Reuses existing S3GroupFile + GroupFile infrastructure. Compliance-grade audit trail with effectively zero risk surface.

The opportunity. Plansight's small-group medical census pull from EN was the original integration win — we get accurate roster + family structure for community-rated quoting. EN's quote-census response also includes employmentCompensation.annualBenefitSalary, employmentInformation.benefitHireDate / jobTitle / benefitWorkState, and companyStructureMapping.eligibilityClass / division / department / businessUnit / officeLocation — exactly the inputs LTD/STD volume calculations need. Plansight's ingest at Controller.php:466 drops every one of those fields. Brokers are uploading a separate volume CSV for LTD/STD when EN already has the data.

What we'd gain. One-click pull-and-go for LTD/STD volume on any group already on EN. No CSV upload step. For renewals, we also get the prior-year approvedBenefitAmount per employee, which is the volume baseline the renewal calc wants.

What it touches. Two halves: (1) the EN ingest in Controller.php grows new fields per employee row; (2) the existing LTD/STD volume builder in Plansight (engineering needs to confirm the exact path — likely a model under app/Models/ + a controller under app/Http/Controllers/Rest/App/) consumes those new fields the same way it consumes CSV-uploaded ones. The two paths converge into one volume model.

Why it pairs well with #11. Same code path. Both are additions to the existing successful census-pull flow. A single sprint can ship both — #11 alone, #12 alone, or paired.