# Onboarding

## Request Access

{% hint style="info" %}
To begin using the API, you’ll need to work with the HealthSherpa ICHRA team to set up your integration. Email <ichrasupport@healthsherpa.com> to get started.
{% endhint %}

All API requests to the HealthSherpa ICHRA APIs require authentication via API keys. Each partner will receive unique keys for each environment (Staging and Production). The API Key must be passed via request headers for all endpoints.&#x20;

Contact <ichra@healthsherpa.com> to help get set up with an API Key.&#x20;

### API Keys & Staging Authentication

Your API key authenticates all requests across the HealthSherpa ICHRA API surface:

| API                                           | Authentication                                                                          |
| --------------------------------------------- | --------------------------------------------------------------------------------------- |
| QuoteConnect (`/quotes`, `/aptc_estimates`)   | `x-api-key` header (required)                                                           |
| EnrollConnect (`/api/v1/applications/...`)    | `x-api-key` header (required)                                                           |
| Application Deeplink (`/public/ichra/off_ex`) | `x-api-key` header (optional in production, enables automatic `_agent_id` allowlisting) |
| Webhooks                                      | Configured separately during onboarding                                                 |

Include your API key in all requests using the `x-api-key` header.

**Example Request**

```http
POST /api/v1/quotes HTTP/1.1
Host: api.ichra-staging.healthsherpa.com
x-api-key: your_api_key_here
Content-Type: application/json
Accept: */*
```

**Example cURL**

```bash
curl -X POST https://api.ichra-staging.healthsherpa.com/api/v1/quotes \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "zip_code": "12345",
    "fip_code": "01001",
    "household_income": 50000,
    "plan_year": 2026,
    "applicants": [
      {
        "age": 35,
        "relationship": "primary",
        "smoker": false
      }
    ]
  }'
```

***

#### Base URLs

<table><thead><tr><th width="137.5">Environment</th><th width="336.5">QuoteConnect &#x26; EnrollConnect</th><th>Deeplink</th></tr></thead><tbody><tr><td>Staging</td><td><code>https://api.ichra-staging.healthsherpa.com</code></td><td><code>https://staging.healthsherpa.com</code></td></tr><tr><td>Production</td><td><code>https://api.ichra.healthsherpa.com</code></td><td><code>https://www.healthsherpa.com</code></td></tr></tbody></table>

{% hint style="info" %}
In Staging, the Deeplink API requires Basic Auth in addition to the API key. Contact your onboarding representative for the Staging basic authentication credentials. QuoteConnect and EnrollConnect use only the `x-api-key` header in both environments.
{% endhint %}

#### Getting Started

Once you have your API key, follow this progression:

1. **Start with QuoteConnect**: Call `POST /quotes` in staging to verify your key works and confirm plan data for your target states and carriers.
2. **Choose your enrollment path**: Use the `api_enrollment` and `deeplink_enrollment` flags on the quote response to determine which path each plan supports. See [Enrollment Decision Path](/integration-guide/enrollment-decision-path.md).
3. **Integrate enrollment:**
   * **EnrollConnect (recommended):** Build your enrollment forms and use the full lifecycle API to create, update, submit, and manage applications programmatically. See [EnrollConnect API](/api-reference/endpoints/enrollconnect-api.md).
   * **Application Deeplink:** Redirect users to HealthSherpa's hosted enrollment UI with pre-filled data. See [Application Deeplink API](https://docs.ichra.healthsherpa.com/api-reference/endpoints/application-deeplink-api).
4. **Set up Webhooks**: Subscribe to Submission Confirmation and Policy Status events to track enrollment lifecycle changes. See [Webhooks](https://docs.ichra.healthsherpa.com/api-reference/webhooks-api).
5. **Move to production**: Request production API keys from your account manager.

***

#### Deeplink-Specific Setup

**What is `_agent_id`?**

The `_agent_id` is a unique identifier tied to an agent's login in the HealthSherpa UI. It determines which agent account the application is associated with, meaning the application will appear under that agent's dashboard in HealthSherpa. This is separate from the `agent_of_record` fields used for commissions and carrier submissions.

**Allowlisting**

If using the Application Deeplink:

* The `_agent_id` must be set up in an allowlist before calls can be made in production. Reach out to the team and we will set your agency up.
* To support using the `_agent_id` of another agent/agency, authenticate the request via your API key. We automatically allowlist any valid `_agent_id` downstream when authenticated.

{% hint style="info" %}
EnrollConnect does not require `_agent_id` allowlisting. The `_agent_id` parameter is optional for EnrollConnect.
{% endhint %}

***

#### Key Management

* API keys are provisioned during onboarding.
* To rotate or request new keys, contact your HealthSherpa account manager.
* Never expose your API key in client-side code.
* HealthSherpa may rotate or revoke keys for security reasons.


---

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