# Integration Setup

### Overview

This guide explains how to connect your system to the HealthSherpa ICHRA APIs, covering QuoteConnect (quoting and APTC estimation), enrollment deeplinks, EnrollConnect (programmatic enrollment), and webhook notifications.

All API calls should be made from your **backend server**, not your frontend application. This ensures that:

* API keys remain private.
* Sensitive user data is protected.
* Deeplink redirects function correctly without CORS issues.

### API Components

<table><thead><tr><th width="144.5">Component</th><th width="276.5">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td><strong>QuoteConnect</strong></td><td><code>POST /quotes</code></td><td>Retrieves ACA plan data and premiums for a given household.</td></tr><tr><td><strong>QuoteConnect</strong></td><td><code>POST /aptc_estimates</code></td><td>Estimates subsidy eligibility. (Standalone estimate; also available through <code>/quotes</code> with <code>household_income</code>.)</td></tr><tr><td>Deeplink API</td><td><code>POST /ichra/off_ex</code></td><td>Prefills an enrollment application and returns a redirect URL to HealthSherpa's enrollment flow.</td></tr><tr><td>EnrollConnect</td><td><code>POST /api/v1/applications</code></td><td>Full lifecycle enrollment API: create, update, submit, cancel, terminate.</td></tr><tr><td>Webhooks</td><td>Custom endpoint on your system</td><td>Receives real-time updates when applications or policies change status.</td></tr></tbody></table>

Each endpoint can be used independently or combined to power your platform’s ICHRA workflows.\
For workflow examples, see [Use Cases](/integration-guide/use-cases.md).

#### Recommended progression

1. Pick an [integration playbook](/getting-started/integration-playbooks.md) matching your business goals.
2. Implement required endpoints.
3. Expand to additional playbooks as needed.

### QuoteConnect

Use the **QuoteConnect API** to retrieve available ACA plans for a household.

**Endpoint:** \
`POST /quotes`

**When to use:**\
During plan shopping or affordability modeling.

**Response:**\
Returns ACA plans and pricing available for the family scenario. Quotes can be for on-exchange or off-exchange.

### Deeplink API

Once a plan is selected, use the **Deeplink API** to generate a prefilled enrollment link.

**Endpoint:**\
`POST /ichra/off_ex`

**Key points:**

* Must be called from your **backend**.
* Returns an HTTP `302` redirect with a `Location` header.
* Your backend should capture that URL and either:
  * Redirect the user directly, or
  * Return it to your frontend for client-side navigation.

**Example (Python / Flask):**

```python
import requests
from flask import Flask, redirect

app = Flask(__name__)
API_KEY = "your_api_key_here"
API_URL = "https://staging.healthsherpa.com/public/ichra/off_ex"

@app.route("/enroll", methods=["POST"])
def enroll():
    payload = {...}  # your enrollment data
    res = requests.post(API_URL,
                        headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
                        json=payload,
                        allow_redirects=False)
    redirect_url = res.headers.get("Location")
    return redirect(redirect_url or "/", code=302)
```

{% hint style="info" %}
See the Flask Staging Proxy Example
{% endhint %}

#### ⚠️ .NET Clients

In .NET, `HttpClient` follows redirects automatically by default. This causes the secure query parameters that enable login bypass to be lost.

**An example fix:**

```csharp
var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler);
var response = await client.PostAsync(apiUrl, content);

if (response.StatusCode == HttpStatusCode.Found)
{
    var redirectUrl = response.Headers.Location.ToString();
    // Redirect user manually
}
```

### EnrollConnect API

Once a plan is selected, use the EnrollConnect API for full programmatic enrollment without the HealthSherpa UI.

Endpoint: `POST /api/v1/applications`

Key points:

* Create a draft application, update it, and submit when ready.
* Every response includes an `errors` array indicating what is still needed.
* Returns JSON responses (not redirects).
* Supports cancel and terminate for post-submission lifecycle management.

See the [EnrollConnect API documentation](/api-reference/endpoints/enrollconnect-api.md) for the full specification.

### Webhooks

Use webhooks to stay updated when enrollments are submitted or policies change status.

**Setup:**\
Provide your webhook URL to your HealthSherpa account manager.\
Your endpoint should:

* Accept POST requests
* Respond with HTTP 200 OK

**Example Payload:**

```json
{
    "transaction_id": "123456789",
    "policy_status": "effectuated",
    "event_type": "sync",
    "event_timestamp": "2025-06-15T14:30:00Z",
    "external_id": "a1b2c3d4e5f6g7h8i9j0",
    "policy_aor_npn": "12345678",
    "submitter_npn": "87654321",
    "npn_used_at_submission": "87654321"
}
```

### Testing in Staging

Before going live:

* Use your staging API key.
* Verify all calls work as expected:
  * `/quotes` returns valid plan data
  * `/aptc_estimates` returns subsidy information (if using)
  * `/ichra/off_ex` returns a redirect URL
  * `/api/v1/applications` creates a draft (if using EnrollConnect)
  * Webhooks are received successfully
* Once tested, request production credentials.


---

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