# 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 review-gated enrollment and policy status 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 when your API key is active. Enrollment sessions, direct enrollment, and policy status require additional review and approval before use. 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.

## Current Public API Surface

- `GET /v1/ping`
- `GET /v1/reference/counties`
- `GET /v1/reference/issuers`
- `GET /v1/reference/providers`
- `POST /v1/quotes`
- `POST /v1/enrollment-sessions` (approval required)
- `GET /v1/policy-status/applications` (approval required)
- `GET /v1/policy-status/applications/{confirmation_id}` (approval required)
- `GET /v1/enrollments` (approval required)
- `POST /v1/enrollments` (approval required)
- `PUT /v1/enrollments/{enrollment_id}` (approval required)
- `GET /v1/enrollments/{enrollment_id}` (approval required)
- `POST /v1/enrollments/{enrollment_id}/cancellations` (approval required)
- `POST /v1/enrollments/{enrollment_id}/submissions` (approval required)
- `GET /v1/enrollments/{enrollment_id}/payment_redirect` (approval required)
- `POST /v1/enrollments/{enrollment_id}/supporting_documentation` (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
- Status API

Available upon review:

- On-Exchange Enrollment Session
- Off-Exchange Enrollment API

Planned:

- 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.
- On-Exchange Enrollment Session and Off-Exchange Enrollment API 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 server, 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`
- a ZIP code can cross state lines; each county's `state` matches its `fips_code`

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.

## GET /v1/reference/providers

Searches healthcare providers (individuals and facilities) by name near a ZIP code. Use the returned 10-digit `npi` values when referencing providers in later requests. This endpoint is search-only; there is no list-all mode.

Inputs:

- `query` (required): provider or facility name search term.
- `zip_code` (required): five-digit ZIP code used for the near-ZIP search.
- `exchange` (required): marketplace channel to search, `on_exchange` or `off_exchange`.
- `page[number]` (optional): page number (mirrors quoting's `page.number`). Defaults to 1; values below 1 are treated as 1.
- `page[size]` (optional): results per page (mirrors quoting's `page.size`), from 1 to 50. Defaults to 50; values outside this range resolve to 50.

Response (the same `{ <results>, meta }` envelope as quoting):

- `providers[]`: provider results for the current page. Each entry includes `npi`, `first_name`, `last_name`, `organization_name`, `display_name`, `credential`, `entity_type`, `specialty`, `specialization`, and address fields (`address_line_1`, `city`, `state`, `zip_code`).
- `meta`: `page_number`, `page_size`, and `result_count` describe the pagination (matching quoting's `meta`). A search with no matches returns `providers: []` with `meta.result_count` 0.

Common errors:

- `400 invalid_request`: `query`, `zip_code`, or `exchange` is missing, or `exchange` is not `on_exchange`/`off_exchange`.

## POST /v1/quotes

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

Inputs include:

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

`household.applicants[].member_id` is a required caller-supplied applicant identifier. Use a stable non-empty string from your system, such as `applicant-1`; it is separate from `relationship`, which identifies the applicant as `primary`, `spouse`, or `dependent`.

Required quote applicant fields are `member_id`, `age`, `relationship`, and `uses_tobacco`. Optional applicant fields include `gender` and marketplace screening flags.

Responses include a homogeneous `plans[]` array for the requested `coverage_type`. Each 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.

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 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 direct enrollment 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`).
- For `agent_assisted`, `location.state` is required. For `self_service`, at least one of `location.state` or top-level `plan_id` is required.

Optional inputs:

- `external_id` (strongly recommended; echoed in the response; must not contain PII).
- `plan_id` (HIOS ID; pre-selects the plan in the flow; only accepted when `context.flow` is `self_service`).
- `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 enrollment 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 and both flows require approved on-exchange enrollment access (`onExchangeEnrollmentRequestApprovalStatus = "approved"`): `context.flow = "agent_assisted"` also requires a healthy HealthSherpa Marketplace OAuth link (account approved, integration `active`, on-exchange capability `ready`, and the access token unexpired or refreshable) plus an OAuth-linked HealthSherpa Marketplace agent whose agency is approved for enrollment deeplink URL generation; `context.flow = "self_service"` also requires a configured deeplink agent ID. The self-service gate does not consult the OAuth link, and the agent-assisted gate does not consult the deeplink agent ID.

## GET /v1/policy-status/applications

Approval-gated on-exchange policy status API for listing applications tied to the OAuth-linked agent account. Request access at `https://one.healthsherpa.com/portal.html` and link a HealthSherpa Marketplace OAuth account with the `policy_status_api` 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.

Required query parameters:

- `exchange` (`on_exchange` only)
- `plan_year` (integer)

Optional query parameters:

- `limit` (1-100, default 25)
- `offset` (0 or greater, default 0)

Response:

- `applications[]` summary rows with `confirmation_id`, `external_id`, `plan_year`, and `exchange_type`
- `pagination` with `limit` and `offset`

Unsupported query parameters return `400 invalid_request`. `403 forbidden` can mean the API key was rejected at the edge or the linked Marketplace account lacks the `policy_status_api` 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/policy-status/applications/{confirmation_id}

Approval-gated on-exchange policy status API for reading carrier policy and payment status for one application.

Required query parameters:

- `exchange` (`on_exchange` only)
- `plan_year` (integer)

Response:

- `policy_statuses[]` entries with `exchange_assigned_policy_id`, `issuer_hios_id`, `effective_date`, `status`, `payment_status`, balance fields, `paid_through_date`, `grace_period_start_date`, and `updated_at`

Requires the same linked Marketplace OAuth account and `policy_status_api` scope as the list endpoint. 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.

## POST /v1/enrollments

Approval-gated direct enrollment API for partners that need API-level control over off-exchange applications. This is a direct application-create path and is separate from `POST /v1/enrollment-sessions`, which returns HealthSherpa links.

Behavior:

- Include `context.product = "ichra"` and `context.exchange = "off_exchange"`. Other products and exchanges are not supported for direct enrollment at this time; use `POST /v1/enrollment-sessions` for on-exchange enrollment.
- Request body must be a JSON object. Send the application payload at the request root plus the HealthSherpa ONE `context` object; do not nest application fields under `enrollment`.
- Required create fields are `context.product = "ichra"`, `context.exchange = "off_exchange"`, `context.plan_year`, `plan_hios_id`, `applicants.primary`, and `residential_address`. Do not send root `plan_year`; HealthSherpa ONE sets the application `plan_year` from `context.plan_year`.
- Core request groups: `applicants.primary`, `applicants.dependents[]`, `residential_address`, `mailing_address`, `hra`, `hra.employer`, `special_enrollment_period`, `attestations`, `signatures`, `communication_preferences`, `analytics`, and `american_indian_or_alaskan_native_in_household`.
- Applicant fields include identity (`first_name`, `middle_name`, `last_name`, `suffix`, `ssn`, `itin`, `date_of_birth`, `gender`), demographics (`race_ethnicity`, `hispanic_origin`, language fields), contact (`email`, `phone`, `phone_type`, `secondary_phone`), eligibility flags (citizenship, residency, tobacco, student, disability, Medicare/Medicaid, incarceration, immigration), existing coverage, guardian, responsible party, translator, and applicant signature fields. Dependents also include `relationship` and optional `alternate_address`.
- HRA fields include `offered_hra`, `type`, `amount`, `contribution_covers`, `used_for_spousal_or_family_premiums`, `start`, employer details, `premium_payer`, `household_size`, `annual_household_income`, and `annual_household_income_determination`.
- SEP fields are `special_enrollment_period.event_type` and `event_date`; common ICHRA SEP is `offered_ichra`. `pregnancy` is accepted in CO, VA, NJ, and MD.
- Attestations, signatures, communication preferences, addresses, existing coverage, payment instructions, policy details, events, and error-detail schemas are fully enumerated in `openapi.json`.
- HealthSherpa ONE uses `context` only for routing and sets the application `plan_year` from `context.plan_year`, and applies `_agent_id` and `tpa_slug` from the caller's approved account setup. Caller-supplied root `plan_year` is overwritten from `context.plan_year`. Caller-supplied `_agent_id`, `tpa_slug`, `actor.agent_id`, and `agent_of_record` return `400 invalid_request`.
- `Idempotency-Key` is required.
- Successful responses include the application data and current validation state. Successful application responses can include `policy_status`, `document_status`, `payment_instructions`, carrier-reported `payment`, `policies[]`, stored `application`, `supports_changes`, `can_change_plan`, `can_report_change`, `next_actions[]` with HealthSherpa ONE `/v1/enrollments` hrefs, submission-readiness `errors[]`, and lifecycle `events[]`.
- In successful responses, `errors[]` is submission-readiness data; an empty array means the application is ready to submit. Service failures (validation, idempotency-key, authorization, service availability) use top-level `errors[]` with `code`, `message`, and optional `field`. Failures blocked at the API edge (API Gateway and WAF) use the unified `error` envelope instead — most notably a missing or invalid API key (`403 forbidden`), plus `413`, `415`, edge `429`, and gateway `502`/`504`.

## GET /v1/enrollments

Approval-gated direct enrollment API for listing off-exchange applications for the approved account. Send required query parameters `product=ichra` and `exchange=off_exchange` so HealthSherpa ONE can validate the direct-enrollment routing channel. Supported filters are `policy_status`, `external_id`, `plan_year`, `issuer_hios_id`, `plan_hios_id`, `employer_external_id`, and `updated_since`. Use `limit` and `offset` for pagination; `limit` must be 1-100 and defaults to 25, and `offset` must be 0 or greater and defaults to 0. The response includes `applications[]` summary rows and `pagination` with `limit`, `offset`, and `total`. Do not send unsupported query parameters such as `include_events`; unsupported list controls return `400 invalid_request`. Service failures use top-level `errors[]` with `code`, `message`, and optional `field`; failures blocked at the API edge use the unified `error` envelope.

## PUT /v1/enrollments/{enrollment_id}

Approval-gated direct enrollment API for updating an off-exchange application.

Behavior:

- Request body must be a JSON object.
- Send the HealthSherpa ONE `context` object with `product = "ichra"`, `exchange = "off_exchange"`, and `plan_year`.
- Treat `PUT` as a full replacement-style update. Send the full current application payload, including unchanged fields you want to preserve. When sending `applicants.primary`, include the full current primary applicant object; omitted primary fields may be cleared.
- HealthSherpa ONE maps `context.plan_year` to the application `plan_year`; `context` is not part of the stored application payload.
- Before submission, all application fields may be updated. After submission, carrier support controls what can change; check `supports_changes`, `can_change_plan`, and `can_report_change` on `GET /v1/enrollments/{enrollment_id}?product=ichra&exchange=off_exchange` before attempting post-enrollment changes.
- HealthSherpa ONE applies `_agent_id` and `tpa_slug` from the caller's approved account setup. Send plan year as `context.plan_year`, not root `plan_year`. Caller-supplied `_agent_id`, `tpa_slug`, `actor.agent_id`, and `agent_of_record` return `400 invalid_request`.
- `Idempotency-Key` is not required.
- Successful responses include the updated application data and current submission-readiness `errors[]`. Service failures use top-level `errors[]` with `code`, `message`, and optional `field`; failures blocked at the API edge use the unified `error` envelope.

## GET /v1/enrollments/{enrollment_id}

Approval-gated direct enrollment API for reading an application. Send required query parameters `product=ichra` and `exchange=off_exchange` so HealthSherpa ONE can validate the direct-enrollment routing channel. HealthSherpa ONE returns the application details for the supplied id, including validation state, policy status, payment instructions, policies, and events when available. Do not send unsupported read query parameters such as `include_events`; only `product` and `exchange` are supported. Do not send `plan_year` on GET; applications are read by id, and the application `plan_year` is returned in the response. 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.

## POST /v1/enrollments/{enrollment_id}/cancellations

Approval-gated direct enrollment API for cancelling an off-exchange application that is pending effectuation. Not all carriers support cancellation; read the application first and check the returned carrier capabilities before calling. Send the HealthSherpa ONE `context` object with `product = "ichra"` and `exchange = "off_exchange"`. A successful call returns `202 Accepted` with `application_id`, `policy_status`, optional `effective_date`, and `updated_at`. If a network timeout or other unknown-result failure occurs after calling cancel, poll `GET /v1/enrollments/{enrollment_id}?product=ichra&exchange=off_exchange` before retrying so an already-accepted cancellation does not come back as a misleading not-allowed/no-op retry response. Service failures use top-level `errors[]` with `code`, `message`, and optional `field`; `400` means cancellation is not allowed for the application or carrier. Failures blocked at the API edge use the unified `error` envelope.

## POST /v1/enrollments/{enrollment_id}/terminations

Approval-gated direct enrollment API for terminating an active off-exchange policy before its natural expiration date. Not all carriers support termination; read the application first and check the returned carrier capabilities before calling. Send the HealthSherpa ONE `context` object with `product = "ichra"` and `exchange = "off_exchange"`. A successful call returns `202 Accepted` with `application_id`, `policy_status`, optional `effective_date`, and `updated_at`. If a network timeout or other unknown-result failure occurs after calling terminate, poll `GET /v1/enrollments/{enrollment_id}?product=ichra&exchange=off_exchange` before retrying so an already-accepted termination does not come back as a misleading not-allowed/no-op retry response. Service failures use top-level `errors[]` with `code`, `message`, and optional `field`; `400` means termination is not allowed for the application or carrier. Failures blocked at the API edge use the unified `error` envelope.

## POST /v1/enrollments/{enrollment_id}/submissions

Approval-gated direct enrollment API for submitting an off-exchange application to the carrier. Send the HealthSherpa ONE `context` object with `product = "ichra"` and `exchange = "off_exchange"`; `plan_year` is not required for submission. Before calling, read the application and check `errors[]`; an empty array means the application is ready to submit, and outstanding errors cause submission to fail with `422`. A successful call returns `202 Accepted`; submission processing can continue asynchronously, so poll `GET /v1/enrollments/{enrollment_id}?product=ichra&exchange=off_exchange` until `policy_status` reflects the final outcome. If a network timeout or other unknown-result failure occurs after calling submit, poll readback before retrying so you do not turn an already-accepted submission into a duplicate/no-change response. For carriers that support post-enrollment changes, call `PUT /v1/enrollments/{enrollment_id}` to send supported changes, then call this endpoint again to resubmit the tracked changes. The API returns `422` if no changes have been made since the last submission. Service failures use top-level `errors[]` with `code`, `message`, and optional `field`; failures blocked at the API edge use the unified `error` envelope.

## GET /v1/enrollments/{enrollment_id}/payment_redirect

Approval-gated direct enrollment API for retrieving carrier payment redirect data for an off-exchange application. Send required query parameters `product=ichra` and `exchange=off_exchange` so HealthSherpa ONE can validate the direct-enrollment routing channel. Use this when the application response includes `payment_instructions.payment_redirect_supported = true`. The response includes `method = "POST"`, the carrier `endpoint`, and `fields[]` entries with `name` and `value`. Build a browser form POST to `endpoint` with every returned field as a hidden input. Include each field exactly as provided; do not filter, rename, interpret, or modify carrier-specific fields. Service failures use top-level `errors[]` with `code`, `message`, and optional `field`; `422` means payment redirect is not supported for this carrier. Failures blocked at the API edge use the unified `error` envelope.

## POST /v1/enrollments/{enrollment_id}/supporting_documentation

Approval-gated direct enrollment API for uploading SEP supporting documentation to an off-exchange application. Use this when `GET /v1/enrollments/{enrollment_id}?product=ichra&exchange=off_exchange` returns `document_status = "required"` or the application indicates that supporting documentation is needed. Send the HealthSherpa ONE `context` object with `product = "ichra"` and `exchange = "off_exchange"`, `document_type = "sep"`, and a PDF, JPEG, or PNG file. Requests may use `multipart/form-data` with a binary `file`, or `application/json` with `file.filename`, `file.content_type`, and base64 `file.content_base64`. HealthSherpa ONE does not persist the uploaded file after processing. Service failures use top-level `errors[]` with `code`, `message`, and optional `field`; failures blocked at the API edge use the unified `error` envelope.

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

HealthSherpa-owned 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.
- Direct enrollment endpoints use top-level `errors[]` instead of `error` for service failures; edge-blocked failures (such as a missing or invalid API key) still use `error`.

`details` is used for HealthSherpa-owned field-specific validation errors keyed by request path on endpoints that use the `{ "error": ... }` envelope.
Direct enrollment service failures use `{ "errors": [{ "code": "invalid_field_value", "message": "must be valid", "field": "plan_hios_id" }] }`; `field` is omitted when no request path is available. Because edge-blocked failures use the `{ "error": ... }` envelope on these endpoints too, clients should check for both `errors` and `error`.

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

Portal status behavior:

- Request review and technical setup are separate states. An approved request means the review decision is complete; it does not by itself assert that every runtime prerequisite is set up.
- Approved on-exchange requests show **Consumer self-service** and optional **Agent-assisted** as alternative flows, not sequential steps. Both use `POST /v1/enrollment-sessions` and return HealthSherpa browser links.
- Approved off-exchange requests show one **Account setup** state for the Off-Exchange Enrollment API.
- User-facing setup states are **Setup complete**, **Setup in progress**, **Action required**, **Contact support**, and **Refresh needed**.
- For agent-assisted enrollment, **Action required** means the developer must connect or reconnect their HealthSherpa Marketplace account through the OAuth linking flow. Developers who only use consumer self-service do not need to complete that action.
- If Marketplace OAuth linking is disabled or unavailable, the portal routes agent-assisted recovery to support instead of showing an unusable reconnect action.
- Every API request is still authorized at runtime.

Off-Exchange Enrollment API:

- Developers can submit a freeform reason for requesting off-exchange enrollment access.
- The `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` endpoints are available only after approval and account setup.
- The Off-Exchange Enrollment API includes listing, creation, full replacement-style updates, cancellation, termination, submission, payment redirect data, supporting document upload, and readback. The response carries validation state, payment instructions, policy status, document status, and lifecycle events.
- The full create, update, and response schemas are documented in `openapi.json`.

On-Exchange Enrollment:

- Developers can request additional portal access for on-exchange enrollment sessions generated through `POST /v1/enrollment-sessions`. Approved on-exchange enrollment access is required for both `context.flow = "agent_assisted"` and `context.flow = "self_service"`.
- The Marketplace OAuth link is visible to approved developers without requiring the on-exchange enrollment request first.

Review-gated on-exchange and off-exchange enrollment 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 review-gated enrollment workflows as unavailable unless access is approved and the relevant portal setup row is **Setup complete**.

## Contact

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