# Integration Playbooks

### Decision Matrix

<table><thead><tr><th>Goal</th><th width="224">Start Here</th><th>Add Next</th></tr></thead><tbody><tr><td>Show plans/prices only</td><td>Quote-Only</td><td>Affordability Modeling or Group Enrollment</td></tr><tr><td>Model employer contribution strategy</td><td>Affordability Modeling</td><td>Group Enrollment</td></tr><tr><td>Enroll members in coverage</td><td>Enrollment</td><td>Status Monitoring</td></tr><tr><td>Run high-volume agent enrollment</td><td>Agent-Assisted Group Enrollment</td><td>Status Monitoring</td></tr><tr><td>Own complete platform journey</td><td>End-to-End Platform Integration</td><td>--</td></tr></tbody></table>

### Playbook 1: QuoteConnect

> Use when you need plan and premium data.

#### At a Glance

| Item               | Value                                                                |
| ------------------ | -------------------------------------------------------------------- |
| Best for           | Shopping, plan comparison, recommendation UX, affordability modeling |
| Complexity         | Low                                                                  |
| Required endpoints | QuoteConnect `POST /api/v1/quotes`                                   |
| Optional endpoints | QuoteConnect `POST /api/v1/aptc_estimates`                           |

#### 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.

#### Workflow

1. Collect household + location inputs.
2. Resolve county/FIPS when required.
3. Call quotes endpoint.
4. 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.

#### Expansion Path

Add Affordability Modeling if employer strategy analysis is needed.

***

### Playbook 2: Affordability Modeling

> Use when employers need contribution strategy analysis before enrollment decisions.

#### At a Glance

<table><thead><tr><th width="198">Item</th><th>Value</th></tr></thead><tbody><tr><td>Best for</td><td>Employer allowance strategy and affordability analysis</td></tr><tr><td>Complexity</td><td>Medium</td></tr><tr><td>Required endpoints</td><td>QuoteConnect <code>POST /api/v1/quotes</code></td></tr></tbody></table>

#### Real ICHRA Scenario

A broker needs to test multiple monthly contribution amounts to evaluate employee affordability outcomes by class.

#### Workflow

1. Generate quotes per modeled household.
2. Compute employee premium exposure after employer allowance.
3. Compare scenarios by class/region.
4. 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.

#### Expansion Path

Add Group Enrollment once strategy is approved and rollout begins.

***

### Playbook 3: Enrollment

> Use when plan selection already happened and you only need enrollment handoff.

#### At a Glance

<table><thead><tr><th width="185.5">Item</th><th>Value</th></tr></thead><tbody><tr><td>Best for</td><td>Platforms enrolling ICHRA participants in off-exchange plans</td></tr><tr><td>Complexity</td><td>Medium to High</td></tr><tr><td>Primary path</td><td>EnrollConnect API (full lifecycle control)</td></tr><tr><td>Fallback path</td><td>Application Deeplink (redirect to HealthSherpa UI)</td></tr><tr><td>Required endpoints</td><td>EnrollConnect: <code>POST /api/v1/applications</code>, <code>PUT .../applications/:id</code>, <code>GET .../applications/:id</code>, <code>POST .../applications/:id/submit</code></td></tr><tr><td>Optional endpoints</td><td>QuoteConnect <code>POST /api/v1/quotes</code>, Webhooks, <code>POST .../cancel</code>, <code>POST .../terminate</code>, <code>POST .../supporting_documentation</code></td></tr></tbody></table>

**Enrollment Path Selection**

Not all carriers support EnrollConnect at launch. Use the `api_enrollment` and `deeplink_enrollment` flags on the QuoteConnect response to determine which path is available for each plan.

```
┌──────────────────────────┐
│  Quote plan via          │
│  QuoteConnect            │
└────────────┬─────────────┘
             │
             v
┌──────────────────────────┐
│ api_enrollment = true?   │──yes──> EnrollConnect API
└────────────┬─────────────┘
             │ no
             v
┌──────────────────────────┐
│ deeplink_enrollment      │
│ = true?                  │──yes──> Application Deeplink
└────────────┬─────────────┘
             │ no
             v
     Not enrollable via
        HealthSherpa
```

See [Supported Carriers](/integration-guide/supported-carriers.md) for which carriers support each path.

**EnrollConnect Workflow (Primary)**

1. **Create draft application** — `POST /api/v1/applications` with applicant data, plan, SEP info, and signatures. Review the `errors` array in the response.
2. **Update as needed** — `PUT /api/v1/applications/:id` to add missing fields or correct errors. Repeat until `errors` is empty.
3. **Upload documents** (if required) — `POST .../supporting_documentation` for carriers that require SEP verification documents.
4. **Submit** — `POST .../submit`. Returns `202 Accepted`.
5. **Handle payment** — If `payment_instructions.payment_redirect_url_supported` is true, use `GET .../payment_redirect` to send the member to the carrier's payment page.
6. **Monitor status** — Poll `GET /api/v1/applications/:id` or subscribe to Policy Status webhooks. Track `policy_status` transitions: `draft` > `pending_effectuation` > `effectuated`.
7. **Cancel or terminate** (if needed) — Use `POST .../cancel` (pre-effectuation) or `POST .../terminate` (post-effectuation).

**Deeplink Workflow (Fallback)**

For carriers where `api_enrollment` is `false` but `deeplink_enrollment` is `true`:

1. Call `POST /public/ichra/off_ex` with applicant and plan data.
2. Capture the `Location` header from the `302` response.
3. Redirect the user or agent to the HealthSherpa enrollment UI.
4. Track submission and policy events via webhooks.

{% hint style="info" %}
Both paths accept the same canonical request schema. Build your payload once and route to either endpoint based on the enrollment flags. As carrier support for EnrollConnect expands, your integration automatically shifts from Deeplink to API without payload changes.
{% endhint %}

**Rules and Constraints**

* Only plans with `api_enrollment: true` can be enrolled via EnrollConnect.
* The `errors` array in every EnrollConnect response tells you what is missing.
* Cancel and terminate are asynchronous (return `202`).
* Payment support varies by carrier. Check `payment_instructions`.
* Deeplink requires `_agent_id`; EnrollConnect does not.

#### Expansion Path

Add Status Monitoring for downstream lifecycle visibility.

***

### Playbook 4: Agent-Assisted Group Enrollment

> Use for batch-style employer rollouts handled by agents/brokers.

#### At a Glance

<table><thead><tr><th width="194">Item</th><th>Value</th></tr></thead><tbody><tr><td>Best for</td><td>Multi-employee quoting + enrollment operations</td></tr><tr><td>Complexity</td><td>High</td></tr><tr><td>Required endpoints</td><td>QuoteConnect <code>POST /api/v1/quotes</code>, EnrollConnect or Deeplink</td></tr><tr><td>Optional endpoints</td><td>Webhooks</td></tr></tbody></table>

**Workflow**

1. Quote each employee household via QuoteConnect.
2. Capture selected plan.
3. Check `api_enrollment` / `deeplink_enrollment` flags.
4. For each employee:
   * **EnrollConnect:** Create and submit application via API.
   * **Deeplink:** Generate one deeplink per employee for agent completion.
5. Track submission/policy events via webhooks.

#### Rules and Constraints

* The `errors` array in every EnrollConnect response tells you what is missing.
* Cancel and terminate are asynchronous (return `202`).
* Payment support varies by carrier. Check `payment_instructions`.
* Deeplink requires `_agent_id`; EnrollConnect does not.

#### Expansion Path

Add Full Composable Experience if platform takes ownership of every step.

***

### Playbook 5: End-to-End Platform Integration

> Use when your platform owns onboarding, shopping, enrollment, and lifecycle operations.

#### At a Glance

<table><thead><tr><th width="223">Item</th><th>Value</th></tr></thead><tbody><tr><td>Best for</td><td>End-to-end ICHRA platform ownership</td></tr><tr><td>Complexity</td><td>High</td></tr><tr><td>Required endpoints</td><td>QuoteConnect + EnrollConnect + Webhooks</td></tr><tr><td>Optional endpoints</td><td>Deeplink (fallback for carriers not yet on EnrollConnect)</td></tr></tbody></table>

#### Real ICHRA Scenario

A single platform supports employer setup, employee plan shopping, enrollment handoff, and post-enrollment monitoring in one system.

#### Workflow

* Onboard employer and employees.
* Resolve county/FIPS and quote plans via QuoteConnect.
* Capture selection.
* Check `api_enrollment` / `deeplink_enrollment` flags.
* **EnrollConnect:** Create, update, and submit application via API. **Deeplink (fallback):** Redirect to HealthSherpa enrollment UI for carriers not yet supporting EnrollConnect.
* Track lifecycle via webhooks.

#### Rules and Constraints

* Keep exchange-mode logic explicit per experience.
* Deeplink remains off-ex.
* Build robust retry/error/idempotency patterns.

#### Expansion Path

Optimize with analytics, quality controls, and automated reconciliation.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ichra.healthsherpa.com/getting-started/integration-playbooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.