Integration Setup

Overview

This guide explains how to connect your system to the HealthSherpa ICHRA APIs, covering quoting, APTC estimation, enrollment deeplinks, 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

Component	Endpoint	Description
Quoting API	POST /quotes	Retrieves ACA plan data and premiums for a given household.
APTC Estimation API	POST /aptc_estimates	Estimates subsidy eligibility. (Redundant if you already call /quotes.)
Deeplink API	POST /ichra/off_ex	Prefills an enrollment application and returns a redirect URL to HealthSherpa’s enrollment flow.
Webhooks	Custom endpoint on your system	Receives real-time updates when applications or policies change status.

Each endpoint can be used independently or combined to power your platform’s ICHRA workflows. For workflow examples, see Use Cases.

Architecture

Below is the recommended high-level flow.

Your backend is the system of record that:

• Authenticates API calls with your x-api-key

• Handles redirects securely

• Receives webhook events

Quoting API

Use the Quoting 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):

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)

See the Flask Staging Proxy Example

⚠️ .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:

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
}

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:

{
    "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:

1. Use your staging API key.

2. Verify all calls work as expected:

   • /quotes returns valid plan data

   • /ichra/off_ex returns a redirect URL

   • Webhooks are received successfully

3. Once tested, request your _agent_id be allow-listed for production.