# HealthSherpa ❮ONE❯ API Docs

> Reference for current public endpoints and approval-gated enrollment workflows in the HealthSherpa developer portal.

## Authentication

- Public API requests use the `x-api-key` header.
- The OpenAPI contract is available at `https://one.healthsherpa.com/openapi.json`.

## Available now

### GET /v1/ping

- Confirms API reachability and key validity.

### GET /v1/reference/counties

- Input: `zip_code` query parameter.
- Returns county options with `name`, `fips_code`, and `state`.
- Use the selected `fips_code` in quote requests.

### GET /v1/reference/issuers

- Inputs: required `state` (two-letter uppercase US code; lowercase is rejected with `400 invalid_request`), optional `plan_year` (integer 2020..2099, defaults to the current ACA plan year).
- Returns one entry per active HIOS issuer with `name` and 5-digit `hios_issuer_id`.
- Entries are sorted by `name` (case-insensitive) and then `hios_issuer_id` as a stable tiebreaker.
- Use the returned `hios_issuer_id` to build issuer filters or validate inbound quote requests.

### POST /v1/quotes

- Inputs include `context`, `location`, and `household`.
- Returns a homogeneous `plans[]` array for the requested `coverage_type`.
- Quotes always return the canonical payload shape.
- Legacy `include` is deprecated and ignored; when supplied, `meta.warnings` includes a deprecation message.
- Use filters, sorting, and pagination to control result selection and order.
- Current docs include examples for medical ACA quoting.

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

## Approval-gated workflows

### POST /v1/enrollment-sessions

- Approval-gated endpoint. Request access in the developer portal at `https://one.healthsherpa.com/portal.html` so HealthSherpa can enable your account for enrollment sessions. Portal access is separate from the per-request authorization described under `403 forbidden` 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.
- For the direct-to-consumer flow (`context.flow = "self_service"`), approval is required and must be requested in the developer portal before use.
- Successful responses include `links.shopping_url` and `links.client_apply_url`. The endpoint does not create downstream application records.
- Optional `Idempotency-Key` header is treated as unique within a 24-hour window.
- The entire `context` object is required (`product`, `exchange`, `coverage_family`, `coverage_type`, `plan_year`, `flow`, `locale`).
- Callers must supply at least one of `location.state` or top-level `plan_id`.
- Strict body: unsupported fields anywhere in the body are rejected with `400 invalid_request`.
- `403 forbidden` can mean the key was rejected at the API edge, or that the developer's HealthSherpa Marketplace setup is not yet in the state the requested flow needs. The check is flow-scoped: `agent_assisted` requires a healthy HealthSherpa Marketplace link (active OAuth connection with an unexpired or refreshable access token); `self_service` requires approved D2C deep-link access and a configured agent ID. Each flow only fails when the gate it actually uses is not satisfied.
- `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. Approval for the On-Exchange Direct-to-Consumer Enrollment API is required before using this flow.
- `context.locale` of `es-MX` renders the hosted page in Spanish.
- `campaign` (UTM, `cid`, `display_phone_number`) is only accepted when `context.flow` is `self_service`.
- `enrollment.hra.amount` is required when `hra` is supplied; `frequency` is required when `amount > 0` (`annually`, `monthly`, `quarterly`, `one_time`).
- `household.household_size` must be positive. Applicants support `relationship`, `date_of_birth` (xor `age`), `sex` (`male`/`female`), `uses_tobacco`, and other screening flags. A household can include at most one `primary` and one `spouse`.

### Off-Exchange Enrollment API

- Draft-based lifecycle: create, validate, submit, manage payment, and track status.
- Supporting documents, cancellation, and termination are modeled explicitly.

## Errors

- `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`: 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.

## Key links

- Human-readable docs: `https://one.healthsherpa.com/docs.html`
- OpenAPI specification: `https://one.healthsherpa.com/openapi.json`