# HealthSherpa ❮ONE❯ Developer Portal

> Public LLM-optimized context for the HealthSherpa ❮ONE❯ developer portal, current public ACA quoting APIs, registration flow, API key management, and approval-gated enrollment workflows.

The canonical public portal is `https://one.healthsherpa.com/`. The production API hostname is `https://api.one.healthsherpa.com`.

API authentication uses the `x-api-key` header. Public quoting APIs are available after signup. Enrollment workflows require additional review and approval before use.

## Current Public API Surface

- `GET /v1/ping`
- `GET /v1/reference/counties`
- `GET /v1/reference/issuers`
- `POST /v1/quotes`
- `POST /v1/enrollment-sessions` (approval required)

The OpenAPI 3.1 contract is available at `https://one.healthsherpa.com/openapi.json`.

## Developer Portal Overview

HealthSherpa ❮ONE❯ is a developer portal for ACA health insurance quoting APIs and selected enrollment workflows.

Available now:

- ACA on-exchange quoting
- ACA off-exchange quoting
- County lookup for ZIP-to-county resolution before quoting

Available upon review:

- Off-Exchange Enrollment API
- D2C Deep Link API workflows

Planned:

- Status API
- Ancillary partner workflows

Getting started:

1. Register through `https://one.healthsherpa.com/register.html`.
2. Confirm your email with the verification link.
3. Use the portal login link when it is sent.
4. Generate and store your API key.
5. Review `https://one.healthsherpa.com/docs.html` and `https://one.healthsherpa.com/openapi.json`.

Important notes:

- Public quoting APIs are available after the signup flow is complete.
- Approval-gated workflows require additional review for compliance and market rules.
- Object schemas may gain optional fields over time, so clients should ignore unknown response properties.

## Vibe Coding Guide

The vibe coding guide is available at `https://one.healthsherpa.com/vibe-coders.html` with an LLM-optimized mirror at `https://one.healthsherpa.com/vibe-coders.html.md`.

It provides static instructions and copy/paste prompts for AI app builders. It does not ship a runnable demo app, local API proxy, dependency tree, or hosted quote builder.

Supported prompt files:

- Google AI Studio: `https://one.healthsherpa.com/prompts/google-ai-studio-healthquote-pro.md`
- Claude: `https://one.healthsherpa.com/prompts/claude-hs-one.skill`
- Codex: `https://one.healthsherpa.com/prompts/codex-healthquote-pro.md`
- Lovable: `https://one.healthsherpa.com/prompts/lovable-healthquote-pro.md`
- Replit: `https://one.healthsherpa.com/prompts/replit-healthquote-pro.md`

Vibe coding security rules:

- Do not paste HealthSherpa API keys into builder chats.
- Store API keys only in server-side secrets or environment variables such as `HEALTHSHERPA_API_KEY`.
- Browser code should call only the app's backend routes.
- Backend routes should call `https://api.one.healthsherpa.com/v1` with the `x-api-key` header.
- Generated apps should resolve ZIP code to county and FIPS code before submitting quote requests.

## Authentication

Public API requests use the `x-api-key` header.

Example:

```http
GET /v1/ping HTTP/1.1
Host: api.one.healthsherpa.com
x-api-key: YOUR_API_KEY
```

## GET /v1/ping

Confirms API reachability and key validity.

Successful responses identify the API environment and confirm that the supplied key was accepted.

Common errors:

- `403 forbidden`: API Gateway rejected the key as missing, invalid, inactive, or unauthorized, or the request was blocked at the edge.
- `429`: request limits exceeded.
- `500 internal_error`: unexpected server-side exception.
- `502`, `503`, `504`: upstream or gateway dependency unavailable.

## GET /v1/reference/counties

Resolves a ZIP code to county options.

Input:

- `zip_code`: five-digit ZIP code query parameter.

Response:

- `counties[]`
- each county includes `name`, `fips_code`, and `state`

Use the selected `fips_code` in quote requests.

## GET /v1/reference/issuers

Lists active QHP issuers in a state for an ACA plan year. Use this to populate issuer filters in shopping UIs or to validate that an inbound quote request targets a known HIOS issuer ID.

Inputs:

- `state` (required): two-letter uppercase US state code (e.g. `FL`, `CA`, `DC`). Lowercase values are rejected with `400 invalid_request`.
- `plan_year` (optional): integer in the inclusive range `2020..2099`. Defaults to the current ACA plan year.

Response:

- `issuers[]`
- each entry includes a sortable display `name` (issuer marketing name when present, legal name otherwise) and the canonical 5-digit `hios_issuer_id`.

Response ordering:

- Sorted by `name` (case-insensitive) and then by `hios_issuer_id` as a stable tiebreaker. Clients can iterate the array directly without re-sorting.

Common errors:

- `400 invalid_request`: `state` is missing or is not a US state code, or `plan_year` is not an integer in `2020..2099`.
- `404 not_found`: no active issuers were found for the state in the requested plan year.

## POST /v1/quotes

Returns ACA plan quotes for the requested coverage type and household.

Inputs include:

- `context`
- `location`
- `household`

Responses include a homogeneous `plans[]` array for the requested `coverage_type`.

Clients can request pricing, documents, details, benefits, quality, sorting, and pagination. Current public docs include examples for medical ACA quoting.

## POST /v1/enrollment-sessions

Approval-gated endpoint. Request access at `https://one.healthsherpa.com/portal.html` so HealthSherpa can enable your account for enrollment sessions during onboarding. Portal access is separate from the per-request authorization described under Errors below: each call is checked only against the marketplace link or deep-link configuration that the chosen `context.flow` actually uses.

Use this endpoint to send the browser to a HealthSherpa-hosted enrollment flow for guided shopping, application preparation, and enrollment completion. Successful responses include `links.shopping_url` and `links.client_apply_url`; the endpoint does not create downstream application records.

Headers:

- `Idempotency-Key` (optional): client-supplied UUID. Treated as unique within a 24-hour window.

Required inputs:

- `context` object and every field inside it: `product` (`aca`), `exchange` (`on_exchange`), `coverage_family` (`medical`), `coverage_type` (`medical`), `plan_year` (integer 2020-2099), `flow` (`agent_assisted` or `self_service`), `locale` (`en-US` or `es-MX`).
- At least one of `location.state` or top-level `plan_id`.

Optional inputs:

- `external_id` (strongly recommended; echoed in the response; must not contain PII).
- `plan_id` (HIOS ID; pre-selects the plan in the hosted flow).
- `client` (`first_name`, `last_name`, `email`, `phone_number`).
- `location` (`zip_code`, `fips_code`, `state`; address-level fields like `address`, `address_2`, `city` are rejected).
- `household` (`annual_income`, `household_size`, `someone_has_employer_coverage`, `applicants[]`; `household_size` must be positive).
- `household.applicants[]` (`relationship` required; at most one `primary` and one `spouse`; `date_of_birth` and `age` mutually exclusive; `sex` accepts `male`/`female`; supports `uses_tobacco`, `pregnant`, `parent_caretaker`, `rejected_by_medicaid_or_chip`, `unemployment`, `has_existing_coverage`, and `ichra`).
- `enrollment.hra` (`amount` required when supplied; `frequency` required when `amount > 0`; allowed frequencies: `annually`, `monthly`, `quarterly`, `one_time`).
- `campaign` (UTM fields, `cid`, `display_phone_number`; only accepted when `context.flow` is `self_service`).

Flow and locale behavior:

- `context.flow`: use `agent_assisted` when an agent is helping the shopper; the agent must sign in to HealthSherpa in the browser before continuing. Use `self_service` when the shopper is completing the flow without an agent sign-in.
- `context.locale`: `es-MX` renders the hosted page in Spanish.

Strictness:

- Unsupported fields anywhere in the body are rejected with `400 invalid_request`.
- `enrollment.special_enrollment_period` and `enrollment.communication_preferences` are not supported.

Response:

- `external_id`: echoed from the request when supplied; otherwise `null`.
- `links.shopping_url`: HealthSherpa public shop URL (`https://healthsherpa.com/public/shop?...`).
- `links.client_apply_url`: HealthSherpa public apply URL (`https://healthsherpa.com/public/apply?...`). Always present.

Errors include `400 invalid_request`, `401 unauthorized`, `403 forbidden`, `413 payload_too_large`, `415 unsupported_media_type`, `429 rate_limited`, `500 internal_error`, `502 bad_gateway`, `503 service_unavailable`, and `504 gateway_timeout`. For enrollment sessions, `403 forbidden` can come from the API edge or from the backend when the developer's HealthSherpa Marketplace setup is not in the state the requested flow needs. The backend check is flow-scoped: `context.flow = "agent_assisted"` requires a healthy HealthSherpa Marketplace OAuth link (account approved, integration `active`, on-exchange capability `ready`, and the access token unexpired or refreshable); `context.flow = "self_service"` requires approved D2C deep-link access (`d2cDeepLinkApiRequestApprovalStatus = "approved"`) and a configured deeplink agent ID. The self-service gate does not consult the OAuth link, and the agent-assisted gate does not consult the D2C/deeplink configuration.

## Compatibility Rules

- Response objects are intentionally open and may gain new optional fields.
- Clients should ignore unknown properties.
- Clients should not rely on object property order.
- Clients should use the published OpenAPI contract for request and response shapes.

## Error Shape

API error responses use a unified error envelope:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed",
    "details": {}
  }
}
```

Common error categories:

- `400 invalid_request`: payload or query validation failed.
- `401 unauthorized`: backend runtime authentication failure when a request reaches a runtime that performs its own authentication.
- `403 forbidden`: API Gateway rejected the key as missing, invalid, inactive, or unauthorized, or the request was blocked at the edge.
- `429`: request limits exceeded.
- `503`: upstream catalog or marketplace dependency unavailable.
- `500 internal_error`: unexpected server-side exception.

## Registration Flow

Developers can request a HealthSherpa ❮ONE❯ API key through `https://one.healthsherpa.com/register.html`.

Required information:

- email
- company
- contact name
- intended use case

Steps:

1. Submit email, company, contact name, and intended use case.
2. Confirm email using the verification link sent by HealthSherpa.
3. Wait for the portal login link when access is ready.
4. Sign in and generate an API key in the developer portal.

Successful submissions start the developer onboarding flow. Email verification is required before access can continue. The portal uses passwordless login links instead of standalone passwords.

## Portal Login And Key Management

Developers request a one-time login link using the same email used for registration.

If a login link is available for that email, the portal sends one shortly. Email verification and approval must already be complete before a portal session is issued.

Authenticated portal actions:

- generate an API key
- reveal a pending API key once
- confirm that the new key has been stored
- test current public endpoints from the built-in API explorer
- sign out of the current portal session

Security notes:

- Login uses a one-time email link.
- Portal sessions are short-lived.
- Newly provisioned keys are intended to be copied and stored immediately.
- If a developer loses a key after the one-time reveal, they should rotate it instead of expecting the key to be shown again.

## Approval-Gated Access Requests

Approved developers can request additional access from inside the portal.

Off-Exchange Enrollment API:

- Developers can submit a freeform reason for requesting off-exchange enrollment access.
- The workflow is modeled around draft creation, validation, submission, payment management, and status tracking.
- Supporting documents, cancellation, and termination are modeled explicitly.

D2C Deep Link API:

- Developers can request additional portal access for direct-to-consumer deep links generated through `POST /v1/enrollment-sessions` with `context.flow = "self_service"`.
- The Marketplace OAuth link for `context.flow = "agent_assisted"` is visible to approved developers without requiring the D2C request first.

Approval-gated workflows should not be treated as generally available until HealthSherpa approves the developer for the relevant access.

## Public Documentation Links

- Developer portal overview: `https://one.healthsherpa.com/index.html.md`
- API documentation: `https://one.healthsherpa.com/docs.html.md`
- API key registration: `https://one.healthsherpa.com/register.html.md`
- Portal login and key management: `https://one.healthsherpa.com/portal.html.md`
- OpenAPI specification: `https://one.healthsherpa.com/openapi.json`
- Human-readable docs page: `https://one.healthsherpa.com/docs.html`

## LLM Crawl Guidance

- Use `https://one.healthsherpa.com/llms.txt` as the index.
- Use this file, `https://one.healthsherpa.com/llms-full.txt`, for consolidated public context.
- Prefer Markdown mirrors and `openapi.json` over rendered HTML when building LLM context.
- Do not infer public API behavior from private repository planning docs or internal RFCs.
- Treat approval-gated enrollment workflows as unavailable unless access has been explicitly approved.

## Contact

Developer support: `developers@one.healthsherpa.com`