# HealthSherpa ❮ONE❯ Developer Portal

> HealthSherpa ❮ONE❯ gives developers access to ACA quoting APIs, enrollment workflows, and approval-gated policy status readback through public docs, self-serve registration, and a passwordless developer portal.

The canonical public portal is `https://one.healthsherpa.com/`. Public quoting APIs are available when your API key is active. Enrollment sessions, direct enrollment, and policy status require additional review and approval. API authentication uses the `x-api-key` header. Policy-status calls and `agent_assisted` enrollment-sessions also require a linked HealthSherpa Marketplace OAuth account; `self_service` enrollment-sessions use a configured deeplink agent ID and do not consult OAuth.

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`.
- [Onboarding](https://one.healthsherpa.com/docs/getting-started/onboarding.html.md): Sign up, API key setup, quoter integration, and enrollment access requests.
- [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. The request body is strict: fields the API does not recognize, at any depth, are rejected with `400 invalid_request`. 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. If you linked before policy status was enabled, use **Re-link account** on the API Access page; token refresh does not add new scopes to an existing link.
- `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 enrollment, off-exchange enrollment, and policy status 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.