# HealthSherpa ❮ONE❯ Developer Portal

> HealthSherpa ❮ONE❯ gives developers access to ACA quoting APIs, the available-now agent enrollment session, and review-gated on-exchange and off-exchange enrollment workflows through public docs, self-serve registration, and a passwordless developer portal.

The canonical public portal is `https://one.healthsherpa.com/`. Public quoting APIs and the On-Exchange Agent Enrollment Session are available now. On-Exchange Enrollment Session and Off-Exchange Enrollment API workflows require additional review and approval. API authentication uses the `x-api-key` header.

This file is the curated LLM entrypoint for Context7 and other documentation crawlers. Prefer the Markdown and OpenAPI links below over crawling rendered HTML pages.

## Primary LLM Context

- [Full LLM context](https://one.healthsherpa.com/llms-full.txt): Consolidated public developer documentation for AI assistants and LLM crawlers.

## Public Documentation

- [Developer portal overview](https://one.healthsherpa.com/index.html.md): Platform overview, current capabilities, onboarding flow, planned work, and compatibility notes.
- [API documentation](https://one.healthsherpa.com/docs.html.md): Endpoint reference for `GET /v1/ping`, `GET /v1/reference/counties`, `GET /v1/reference/issuers`, `GET /v1/reference/providers`, `POST /v1/quotes`, the approval-gated `POST /v1/enrollment-sessions`, the approval-gated on-exchange policy status endpoints `GET /v1/policy-status/applications` and `GET /v1/policy-status/applications/{confirmation_id}`, and the approval-gated direct enrollment endpoints `GET /v1/enrollments`, `POST /v1/enrollments`, `PUT /v1/enrollments/{enrollment_id}`, `GET /v1/enrollments/{enrollment_id}`, `POST /v1/enrollments/{enrollment_id}/cancellations`, `POST /v1/enrollments/{enrollment_id}/terminations`, `POST /v1/enrollments/{enrollment_id}/submissions`, `GET /v1/enrollments/{enrollment_id}/payment_redirect`, and `POST /v1/enrollments/{enrollment_id}/supporting_documentation`.
- [Vibe coding guide](https://one.healthsherpa.com/vibe-coders.html.md): Secure copy/paste prompts for app builders, API key handling rules, and starter workflow guidance.
- [OpenAPI specification](https://one.healthsherpa.com/openapi.json): OpenAPI 3.1 contract for the currently available public endpoints.

## Access And Key Management

- [Sign up](https://one.healthsherpa.com/register.html.md): Registration, email verification, and self-serve developer access flow.
- [Portal login and key management](https://one.healthsherpa.com/portal.html.md): Passwordless sign-in, one-time API key reveal, key confirmation, and approval-gated access request workflow.

## Current Public API Surface

- `GET /v1/ping`: Confirm API reachability and key validity.
- `GET /v1/reference/counties`: Resolve ZIP code to county options and FIPS codes. Border ZIPs can return counties from more than one state; each county's `state` matches its `fips_code`.
- `GET /v1/reference/issuers`: List active QHP issuers in a state for a plan year (`name`, `hios_issuer_id`); `plan_year` defaults to the current ACA plan year.
- `GET /v1/reference/providers`: Search providers (individuals and facilities) by name near a ZIP code; returns a paginated `providers[]` array with 10-digit `npi` and address data.
- `POST /v1/quotes`: Request ACA plan quotes for the selected coverage type and household. Required applicant fields are `member_id`, `age`, `relationship`, and `uses_tobacco`; `member_id` is a caller-supplied identifier, separate from `relationship`, and should be a stable non-empty string such as `applicant-1`. `gender` is optional. Each returned plan includes `api_enrollable`; `true` means the quoted plan can be used with the direct off-exchange enrollment API at quote time, while `false` means use quote/display only or another enrollment path. This is not consumer ACA eligibility or a guarantee of successful submission after applicant and carrier validation.
- `POST /v1/enrollment-sessions` (approval required): Create HealthSherpa links (`shopping_url`, `client_apply_url`) that send the browser to an enrollment flow for on-exchange ACA medical plans. Request portal access at `https://one.healthsherpa.com/portal.html`. Runtime `403 forbidden` is flow-scoped and both flows require approved on-exchange enrollment access: `agent_assisted` also requires a healthy Marketplace OAuth link and agency deeplink approval for the OAuth-linked agent; `self_service` also requires a configured deeplink agent ID. See `llms-full.txt` or the OpenAPI `POST /v1/enrollment-sessions` `403` response for the full matrix.
- `GET /v1/policy-status/applications` / `GET /v1/policy-status/applications/{confirmation_id}` (approval required): Alpha release; not all applications have policy status data yet and carrier coverage, accuracy, and completeness are expanding continuously, so treat missing data as expected. On-exchange policy status API for HealthSherpa Marketplace applications visible to the OAuth-linked agent. List requests require `exchange=on_exchange` and `plan_year`, and accept optional `limit` and `offset`; unsupported direct-enrollment filters such as `product`, `policy_status`, `external_id`, issuer/plan ids, employer id, and `updated_since` are rejected. Single-application requests use the Marketplace application `confirmation_id` plus required `exchange=on_exchange` and `plan_year`, and return `policy_statuses[]` with status, payment, balance, grace-period, and update fields when available. Runtime `403 forbidden` requires approved on-exchange enrollment access, a healthy Marketplace OAuth link, and the `policy_status_api` OAuth scope.
- `GET /v1/enrollments` / `POST /v1/enrollments` / `PUT /v1/enrollments/{enrollment_id}` / `GET /v1/enrollments/{enrollment_id}` / `POST /v1/enrollments/{enrollment_id}/cancellations` / `POST /v1/enrollments/{enrollment_id}/terminations` / `POST /v1/enrollments/{enrollment_id}/submissions` / `GET /v1/enrollments/{enrollment_id}/payment_redirect` / `POST /v1/enrollments/{enrollment_id}/supporting_documentation` (approval required): Direct enrollment API for partners that need API-level control over off-exchange applications. List requests send `product=ichra` and `exchange=off_exchange`, support `policy_status`, `external_id`, `plan_year`, `issuer_hios_id`, `plan_hios_id`, `employer_external_id`, `updated_since`, `limit`, and `offset`, and return `applications[]` plus `pagination`. Create requests send the application payload at the request root plus the HealthSherpa ONE `context` object; required create fields are `context.product = "ichra"`, `context.exchange = "off_exchange"`, `context.plan_year`, `plan_hios_id`, `applicants.primary`, and `residential_address`. Update requests send HealthSherpa ONE context fields `product = "ichra"`, `exchange = "off_exchange"`, and `plan_year` plus the full current application payload, including unchanged fields to preserve. Single-application GET requests send required query parameters `product=ichra` and `exchange=off_exchange`; do not send `plan_year` on GET because applications are read by id and return the application plan year in the response. Cancellation requests use `POST /v1/enrollments/{enrollment_id}/cancellations` with `context.product = "ichra"` and `context.exchange = "off_exchange"` after readback confirms the application is pending effectuation and the carrier supports cancellation; successful cancellation returns `202 Accepted` with status-change data. If the cancel result is unknown after a timeout or network failure, poll readback before retrying. Termination requests use `POST /v1/enrollments/{enrollment_id}/terminations` with `context.product = "ichra"` and `context.exchange = "off_exchange"` after readback confirms the policy is active/effectuated and the carrier supports termination; successful termination returns `202 Accepted` with status-change data. If the termination result is unknown after a timeout or network failure, poll readback before retrying. Submit requests use `POST /v1/enrollments/{enrollment_id}/submissions` with context fields `product = "ichra"` and `exchange = "off_exchange"` after readback shows no outstanding `errors[]`; `plan_year` is not required for submission. Payment redirect requests use `GET /v1/enrollments/{enrollment_id}/payment_redirect?product=ichra&exchange=off_exchange` when `payment_instructions.payment_redirect_supported` is true, then render a browser form POST to the returned `endpoint` with every returned `fields[]` entry unchanged. Successful submission returns `202 Accepted`, and clients should poll readback until `policy_status` reflects the final outcome. If the submit result is unknown after a timeout or network failure, poll readback before retrying. Supporting document uploads send `context.product = "ichra"`, `context.exchange = "off_exchange"`, `document_type = "sep"`, and a PDF, JPEG, or PNG file as multipart binary or JSON base64 when SEP documentation is required. Applicant objects are replacement-shaped in practice: when sending `applicants.primary`, include the full current primary applicant object because omitted primary fields may be cleared. Other products and exchanges are not supported for direct enrollment at this time; on-exchange enrollment should use `POST /v1/enrollment-sessions`. HealthSherpa ONE sets the application `plan_year` from `context.plan_year`, applies `_agent_id` and `tpa_slug` from account setup, and rejects caller-supplied `_agent_id`, `tpa_slug`, `actor.agent_id`, and `agent_of_record`. Successful responses can include application data, `next_actions[]` with HealthSherpa ONE `/v1/enrollments` hrefs, submission-readiness `errors[]`, payment instructions, policies, and events. Service failures use top-level `errors[]` with `code`, `message`, and optional `field`; failures blocked at the API edge (such as a missing or invalid API key) use the unified `error` envelope, so handle both shapes.

## Vibe Coding Prompt Files

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

## Compatibility Rules

- Response objects are intentionally open and may gain new optional fields.
- Clients should ignore unknown response properties.
- Clients should not rely on object property order.

## Crawl Guidance

- Crawl only public portal docs, Markdown mirrors, and `openapi.json`.
- Do not infer behavior from private repository planning docs or internal RFCs.
- Treat review-gated on-exchange and off-exchange enrollment workflows as not generally available without review.

## Contact

- [Developer support](mailto:developers@one.healthsherpa.com): Contact for developer onboarding and portal access questions.
- [Human-readable public docs](https://one.healthsherpa.com/docs.html): Browser-oriented documentation page.
- [HealthSherpa website](https://www.healthsherpa.com): Company website.