Integration Playbooks
Choose the integration pattern that matches your current ICHRA goal.
Decision Matrix
Affordability Modeling or Group Enrollment
Model employer contribution strategy
Enroll plans selected elsewhere
Run high-volume agent enrollment
Agent-Assisted Group Enrollment
Own complete platform journey
End-to-End Platform Integration
Optional optimization endpoints
Playbook 1: Quote-Only
Use when you need plan and premium data without enrollment in the same flow.
Shopping, plan comparison, recommendation UX
Real ICHRA Scenario
An employer wants to preview plan options by employee class and geography before deciding contribution design.
An employee or agent wants to shop for available plans.
Collect household + location inputs.
Resolve county/FIPS when required.
Display plans and cost signals.
Rules and Constraints
Quoting supports on-ex and off-ex.
Use off_ex: true for off-ex-only quote results.
If include_non_enrollable_offex: true is enabled, some plans may not be deeplink-enrollable.
Add Affordability Modeling if employer strategy analysis is needed.
Playbook 2: Affordability Modeling
Use when employers need contribution strategy analysis before enrollment decisions.
Employer allowance strategy and affordability analysis
Real ICHRA Scenario
A broker needs to test multiple monthly contribution amounts to evaluate employee affordability outcomes by class.
Generate quotes per modeled household.
Compute employee premium exposure after employer allowance.
Compare scenarios by class/region.
Output affordability summaries for employer decisioning.
Rules and Constraints
Quoting supports both on-ex and off-ex scenarios, each called separately.
By default the off-exchange quote only returns plans that are enrollable with HealthSherpa but you can opt in to showing all available.
Add Group Enrollment once strategy is approved and rollout begins.
Playbook 3: Enrollment Deeplink-Only (Off-Ex)
Use when plan selection already happened and you only need enrollment handoff.
Enrollment initiation from externally selected plans
POST /public/ichra/off_ex
POST /api/v1/quotes, Webhooks
Real ICHRA Scenario
A platform has selected hios_id from its own shopping engine and now needs to launch enrollment with prefilled data.
Validate selected plan context is enrollable with HealthSherpa. This can be done using the Quote API.
Call deeplink endpoint from backend.
Read Location from HTTP 302.
Redirect user/agent to enrollment.
Rules and Constraints
Deeplinking is off-ex only.
Must be backend-initiated.
Success is 302 + Location header, not JSON 200.
HealthSherpa only supports plans that are enrollable through HealthSherpa where we have an integration with the carrier partner.
Add Status Monitoring for downstream lifecycle visibility.
Playbook 4: Agent-Assisted Group Enrollment
Use for batch-style employer rollouts handled by agents/brokers.
Multi-employee quoting + enrollment operations
POST /api/v1/quotes, POST /public/ichra/off_ex
Real ICHRA Scenario
An employer census is loaded, quoted, reviewed by agent team, then enrolled employee-by-employee using deeplinks.
Quote each employee household.
Generate one deeplink per employee.
Track submission/policy events.
Rules and Constraints
If quotes were generated with include_non_enrollable_offex: true, do not deeplink non-enrollable plans.
Keep an explicit “enrollable” validation step before deeplink.
Add Full Composable Experience if platform takes ownership of every step.
Use when your platform owns onboarding, shopping, enrollment, and lifecycle operations.
End-to-end ICHRA platform ownership
Quotes + Deeplink + Webhooks
Real ICHRA Scenario
A single platform supports employer setup, employee plan shopping, enrollment handoff, and post-enrollment monitoring in one system.
Onboard employer and employees.
Resolve county/FIPS and quote plans.
Track lifecycle via webhooks.
Rules and Constraints
Keep exchange-mode logic explicit per experience.
Build robust retry/error/idempotency patterns.
Optimize with analytics, quality controls, and automated reconciliation.
Last updated
