Public OpenAPI 3.1 REST API for ACA plan quoting, county/issuer/provider reference lookups, agent and self-service enrollment sessions, and an approval-gated direct off-exchange (ICHRA) enrollment lifecycle. Auth is x-api-key; enrollment POSTs support Idempotency-Key (24h retention).
{
"openapi": "3.1.0",
"info": {
"title": "HealthSherpa Public API",
"version": "0.1.0",
"description": "Machine-readable contract for the currently available public HealthSherpa endpoints: 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, 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. Object schemas remain additive and clients should ignore response fields they do not recognize.\n\nMost HealthSherpa-owned errors follow the unified `ErrorResponse` schema: `{ \"error\": { \"code\": string, \"message\": string, \"details\"?: object } }`. The direct enrollment endpoints instead return service failures as a top-level `errors[]` array: `{ \"errors\": [ { \"code\": string, \"message\": string, \"field\"?: string } ] }`. Edge-generated failures (API Gateway and WAF, before a request reaches the service) always use the unified `ErrorResponse` envelope, including on the direct enrollment endpoints — most notably a missing or invalid API key (`403 forbidden`)."
},
"servers": [
{
"url": "https://api.one.healthsherpa.com",
"description": "Production"
}
],
"tags": [
{
"name": "Utility"
},
{
"name": "Reference"
},
{
"name": "Quotes"
},
{
"name": "Enrollment Sessions"
},
{
"name": "Enrollments"
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"paths": {
"/v1/ping": {
"get": {
"tags": [
"Utility"
],
"summary": "Confirm API reachability and key validity",
"operationId": "ping",
"responses": {
"200": {
"description": "API request reached the partner API edge and the supplied API key was accepted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PingResponse"
},
"example": {
"environment": "production",
"ok": true
}
}
}
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"502": {
"$ref": "#/components/responses/BadGateway"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
},
"504": {
"$ref": "#/components/responses/GatewayTimeout"
}
}
}
},
"/v1/reference/counties": {
"get": {
"tags": [
"Reference"
],
"summary": "List counties for a ZIP code",
"description": "Returns the counties that overlap the supplied ZIP code. A ZIP code can cross state lines; each returned county's `state` is the canonical state for its `fips_code`. Use the selected fips_code in subsequent quote requests.",
"operationId": "listCounties",
"parameters": [
{
"name": "zip_code",
"in": "query",
"required": true,
"description": "Five-digit ZIP code to resolve.",
"schema": {
"type": "string",
"pattern": "^[0-9]{5}$"
}
}
],
"responses": {
"200": {
"description": "One or more counties found for the ZIP code.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountiesResponse"
},
"example": {
"counties": [
{
"fips_code": "12086",
"name": "Miami-Dade County",
"state": "FL"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"502": {
"$ref": "#/components/responses/BadGateway"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
},
"504": {
"$ref": "#/components/responses/GatewayTimeout"
}
}
}
},
"/v1/reference/issuers": {
"get": {
"tags": [
"Reference"
],
"summary": "List QHP issuers active in a state",
"description": "Returns the QHP issuers active in the requested state and plan year. Each entry combines a sortable display name (issuer marketing name when present, legal name otherwise) with the canonical 5-digit HIOS issuer ID for use in subsequent quote filters.\n\n**Plan year:** the optional `plan_year` query parameter pins the lookup to a specific year and defaults to the current ACA plan year (open enrollment for 2027 begins November 1 2026). Specify `plan_year` explicitly when reconciling enrollments from a prior year or when shopping the next year before the rollover.\n\n**Response ordering:** entries are sorted by `name` (case-insensitive) and then by `hios_issuer_id` as a stable tiebreaker. Clients can iterate the array directly without re-sorting.",
"operationId": "listIssuers",
"parameters": [
{
"name": "state",
"in": "query",
"required": true,
"description": "Two-letter uppercase US state code (e.g. `FL`). Lowercase values are rejected with `400 invalid_request` — clients must upcase before sending.",
"example": "FL",
"schema": {
"type": "string",
"pattern": "^[A-Z]{2}$"
}
},
{
"name": "plan_year",
"in": "query",
"required": false,
"description": "ACA plan year to scope the issuer list to. Defaults to the current ACA plan year when omitted.",
"schema": {
"type": "integer",
"minimum": 2020,
"maximum": 2099
},
"example": 2026
}
],
"responses": {
"200": {
"description": "One or more issuers found for the state.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssuersResponse"
},
"example": {
"issuers": [
{
"name": "Gulf Coast Coverage Co.",
"hios_issuer_id": "33333"
},
{
"name": "Sunshine State Health",
"hios_issuer_id": "12345"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"502": {
"$ref": "#/components/responses/BadGateway"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
},
"504": {
"$ref": "#/components/responses/GatewayTimeout"
}
}
}
},
"/v1/reference/providers": {
"get": {
"tags": [
"Reference"
],
"summary": "Search healthcare providers by name near a ZIP code",
"description": "Searches healthcare providers (individuals and facilities) by name near a ZIP code and returns paginated results with NPI and address data. This is a search-only endpoint; there is no \"list all providers\" mode.\n\nUse the returned 10-digit `npi` values when building provider selections, for example the `providers` field on an enrollment session.\n\n**Channel:** the required `exchange` parameter selects the marketplace channel (`on_exchange` or `off_exchange`).\n\n**Pagination:** results are paginated with the nested `page[number]` and `page[size]` query parameters, mirroring the quoting endpoint's `page` object. `page[number]` defaults to 1 (values below 1 are treated as 1) and `page[size]` accepts 1 to 50, defaulting to 50 (values outside the range resolve to 50). Pagination metadata is returned under `meta` (`page_number`, `page_size`, `result_count`). An empty search returns `providers: []` with `result_count` 0.",
"operationId": "searchProviders",
"parameters": [
{
"name": "query",
"in": "query",
"required": true,
"description": "Provider or facility name search term.",
"schema": {
"type": "string",
"minLength": 1
},
"example": "Smith"
},
{
"name": "zip_code",
"in": "query",
"required": true,
"description": "Five-digit ZIP code used for the geographic (near-ZIP) search.",
"schema": {
"type": "string",
"pattern": "^[0-9]{5}$"
},
"example": "85001"
},
{
"name": "exchange",
"in": "query",
"required": true,
"description": "Marketplace channel to search. Required. One of `on_exchange` or `off_exchange`.",
"schema": {
"type": "string",
"enum": [
"on_exchange",
"off_exchange"
]
},
"example": "on_exchange"
},
{
"name": "page[number]",
"in": "query",
"required": false,
"description": "Page number (mirrors quoting's page.number). Defaults to 1; values below 1 are treated as 1.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"example": 1
},
{
"name": "page[size]",
"in": "query",
"required": false,
"description": "Results per page (mirrors quoting's page.size), from 1 to 50. Defaults to 50; values outside this range resolve to 50.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 50
},
"example": 50
}
],
"responses": {
"200": {
"description": "Provider search results for the current page. An empty search returns an empty `providers` array.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProvidersResponse"
},
"example": {
"providers": [
{
"first_name": "John",
"last_name": "Smith",
"organization_name": null,
"display_name": "John Smith, MD",
"credential": "MD",
"entity_type": "individual",
"npi": "1972113918",
"specialty": "Family Medicine",
"specialization": "General Practice",
"address_line_1": "123 Main St",
"city": "Phoenix",
"state": "AZ",
"zip_code": "85001"
}
],
"meta": {
"page_number": 1,
"page_size": 50,
"result_count": 1
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"502": {
"$ref": "#/components/responses/BadGateway"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
},
"504": {
"$ref": "#/components/responses/GatewayTimeout"
}
}
}
},
"/v1/quotes": {
"post": {
"tags": [
"Quotes"
],
"summary": "Search plans for one coverage type",
"description": "Returns a homogeneous list of quote results for exactly one coverage_type. Send one request for one market and one coverage_type at a time.",
"operationId": "createQuote",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteRequest"
},
"example": {
"context": {
"product": "aca",
"exchange": "on_exchange",
"coverage_family": "medical",
"coverage_type": "medical",
"plan_year": 2026
},
"location": {
"zip_code": "30301",
"fips_code": "13121",
"state": "GA"
},
"household": {
"household_size": 1,
"annual_income": 52000,
"effective_date": "2026-05-01",
"applicants": [
{
"member_id": "applicant-1",
"age": 40,
"date_of_birth": "1986-05-01",
"relationship": "primary",
"uses_tobacco": false,
"pregnant": false,
"blind_or_disabled": false,
"native_american": false
}
]
},
"sort": {
"field": "premium",
"direction": "asc"
},
"page": {
"number": 1,
"size": 20
}
}
}
}
},
"responses": {
"200": {
"description": "Quotes returned successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"502": {
"$ref": "#/components/responses/BadGateway"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
},
"504": {
"$ref": "#/components/responses/GatewayTimeout"
}
}
}
},
"/v1/enrollment-sessions": {
"post": {
"tags": [
"Enrollment Sessions"
],
"summary": "Start an enrollment session",
"description": "Returns URLs to continue enrollment in a browser-mediated HealthSherpa flow. This endpoint always returns deep links and does not create direct enrollment application records.\n\nBoth agent-assisted and consumer self-service use cases are supported. Set `context.flow` to `agent_assisted` for an agent walking a client through enrollment, or to `self_service` for a consumer enrolling themselves. The `campaign.*` block and the top-level `plan_id` field are only accepted in self-service flows.\n\nThe entire `context` object and every field inside it is required so partners declare product, exchange, coverage, plan year, flow, and locale on every request rather than relying on hidden defaults. In `self_service`, supply at least one of `location.state` or top-level `plan_id`. In `agent_assisted`, `location.state` is required.",
"operationId": "createEnrollmentSession",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional partner-supplied request identifier (1–255 chars, `A-Z`, `a-z`, `0-9`, `-`, `_`). Scoped by API key and retained for 24 hours.\n\n- First call: processed normally; the response is captured.\n- Replay (same key + same body): returns the original response verbatim with `Idempotent-Replay: true`.\n- Same key + different body: `422 idempotency_mismatch`.\n- Concurrent retry while the first call is still in flight: `409 idempotency_in_progress`.\n- `429` responses are not stored, so partners can back off and retry transparently.\n- `5xx` responses **are** stored. Retrying a 5xx with the same Idempotency-Key could risk duplicate work, so partners who believe a 5xx was transient must generate a fresh Idempotency-Key to retry.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9_\\-]{1,255}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrollmentSessionRequest"
},
"example": {
"external_id": "crm-lead-abc-123",
"context": {
"product": "aca",
"exchange": "on_exchange",
"coverage_family": "medical",
"coverage_type": "medical",
"plan_year": 2026,
"flow": "self_service",
"locale": "en-US"
},
"plan_id": "12345NY0010001",
"location": {
"zip_code": "10001",
"fips_code": "36061",
"state": "NY"
},
"household": {
"annual_income": 42000,
"household_size": 1,
"applicants": [
{
"relationship": "primary",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane@example.com",
"phone_number": "5551234567",
"date_of_birth": "1990-01-01",
"sex": "female",
"uses_tobacco": false
}
]
}
}
}
}
},
"responses": {
"200": {
"description": "Enrollment session started successfully.",
"headers": {
"X-Request-Id": {
"description": "HealthSherpa ONE request id for tracing and support.",
"schema": {
"type": "string"
}
},
"Idempotent-Replay": {
"description": "Present and set to `true` only when this response is being replayed from a prior call that supplied the same `Idempotency-Key` and request body.",
"schema": {
"type": "string",
"enum": [ "true" ]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrollmentSessionResponse"
},
"example": {
"external_id": "crm-lead-abc-123",
"links": {
"shopping_url": "https://healthsherpa.com/public/shop?external_id=crm-lead-abc-123&fip_code=36061&household_income=42000&household_size=1&people%5Bprimary%5D%5Bage%5D=36&people%5Bprimary%5D%5Bgender%5D=female&people%5Bprimary%5D%5Btobacco%5D=false&state=NY&user_type=consumer&year=2026&zip_code=10001",
"client_apply_url": "https://healthsherpa.com/public/apply?external_id=crm-lead-abc-123&fip_code=36061&household_income=42000&household_size=1&people%5Bprimary%5D%5Bage%5D=36&people%5Bprimary%5D%5Bgender%5D=female&people%5Bprimary%5D%5Btobacco%5D=false&plan_hios_id=12345NY0010001&state=NY&user_type=consumer&year=2026&zip_code=10001"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Returned when this API key is not authorized to call this endpoint, or when the developer's HealthSherpa Marketplace setup is not in the state the requested flow needs.\n\n- `context.flow = \"agent_assisted\"` requires approved on-exchange enrollment access (`onExchangeEnrollmentRequestApprovalStatus = \"approved\"`) and a healthy HealthSherpa Marketplace OAuth link (account approved, integration `active`, on-exchange capability `ready`, and the access token unexpired or refreshable). The OAuth-linked HealthSherpa Marketplace agent must also belong to an agency that is approved for enrollment deeplink URL generation. If HealthSherpa cannot generate `shopping_url` or `client_apply_url` because the agent account or agency is not approved for deeplink access, the API returns `403 forbidden` and does not treat the result as retryable service unavailability.\n- `context.flow = \"self_service\"` requires approved on-exchange enrollment access (`onExchangeEnrollmentRequestApprovalStatus = \"approved\"`) and a configured deeplink agent ID.\n\nBoth flows require approved on-exchange enrollment access. The self-service gate does not consult the OAuth link, and the agent-assisted gate does not consult the deeplink agent ID. Each flow only fails when the configuration it actually uses is not satisfied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"notAuthorized": {
"value": {
"error": {
"code": "forbidden",
"message": "This API key is not authorized to access this endpoint."
}
}
},
"agentDeeplinksNotEnabled": {
"value": {
"error": {
"code": "forbidden",
"message": "Enrollment deeplinks are not available for this HealthSherpa Marketplace agent yet. Confirm the agent account is part of an agency and that the agency has been approved for deeplink access. Contact HealthSherpa support for help enabling this configuration."
}
}
}
}
}
}
},
"409": {
"$ref": "#/components/responses/IdempotencyInProgress"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"422": {
"$ref": "#/components/responses/IdempotencyMismatch"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"502": {
"$ref": "#/components/responses/BadGateway"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
},
"504": {
"$ref": "#/components/responses/GatewayTimeout"
}
}
}
},
"/v1/enrollments": {
"get": {
"tags": [
"Enrollments"
],
"summary": "List direct enrollment applications",
"description": "Approval-gated direct enrollment API for listing off-exchange applications for the approved account. Send `product=ichra` and `exchange=off_exchange` as required query parameters so HealthSherpa ONE can validate the direct-enrollment routing channel. The response is paginated and can be filtered by policy status, partner or employer ids, plan identifiers, plan year, and last-updated timestamp. Only the documented list filters are supported; unsupported query parameters are rejected with `400 invalid_request`. Service failures are returned as a top-level `errors[]` array with `code`, `message`, and optional `field`; failures blocked at the API edge use the unified `error` envelope.",
"operationId": "listEnrollments",
"parameters": [
{
"name": "product",
"in": "query",
"required": true,
"description": "Direct-enrollment product. Must be `ichra`.",
"schema": {
"type": "string",
"enum": [ "ichra" ]
}
},
{
"name": "exchange",
"in": "query",
"required": true,
"description": "Direct-enrollment routing channel. Must be `off_exchange`.",
"schema": {
"type": "string",
"enum": [ "off_exchange" ]
}
},
{
"name": "policy_status",
"in": "query",
"required": false,
"description": "Filter applications by carrier policy status.",
"schema": {
"type": "string",
"enum": [ "draft", "pending_effectuation", "effectuated", "submission_failed", "cancelled", "terminated" ]
}
},
{
"name": "external_id",
"in": "query",
"required": false,
"description": "Filter by the partner-supplied external application id.",
"schema": {
"type": "string"
}
},
{
"name": "plan_year",
"in": "query",
"required": false,
"description": "Filter by application plan year.",
"schema": {
"type": "integer"
}
},
{
"name": "issuer_hios_id",
"in": "query",
"required": false,
"description": "Filter by issuer HIOS id.",
"schema": {
"type": "string"
}
},
{
"name": "plan_hios_id",
"in": "query",
"required": false,
"description": "Filter by plan HIOS id.",
"schema": {
"type": "string"
}
},
{
"name": "employer_external_id",
"in": "query",
"required": false,
"description": "Filter by the employer's external identifier.",
"schema": {
"type": "string"
}
},
{
"name": "updated_since",
"in": "query",
"required": false,
"description": "ISO 8601 timestamp. Returns applications updated after this time.",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum number of applications to return.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 25,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Zero-based pagination offset.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/EnrollmentListResponse"
},
"400": {
"$ref": "#/components/responses/EnrollmentError"
},
"401": {
"$ref": "#/components/responses/EnrollmentError"
},
"403": {
"$ref": "#/components/responses/EnrollmentError"
},
"429": {
"$ref": "#/components/responses/EnrollmentError"
},
"500": {
"$ref": "#/components/responses/EnrollmentError"
},
"502": {
"$ref": "#/components/responses/BadGateway"
},
"503": {
"$ref": "#/components/responses/EnrollmentError"
},
"504": {
"$ref": "#/components/responses/GatewayTimeout"
}
}
},
"post": {
"tags": [
"Enrollments"
],
"summary": "Create a direct enrollment application",
"description": "Approval-gated direct enrollment API for partners that need API-level control over off-exchange applications. Send the application payload at the request root and include the HealthSherpa ONE `context` object for routing. Direct enrollment currently supports `context.product = \"ichra\"` and `context.exchange = \"off_exchange\"`; other products and exchanges are not supported here. Use `POST /v1/enrollment-sessions` for on-exchange enrollment. HealthSherpa ONE uses `context` only for routing and applies the agent and TPA identifiers (`_agent_id`, `tpa_slug`) from your approved account setup; caller-supplied `_agent_id`, `tpa_slug`, `actor.agent_id`, and `agent_of_record` are rejected.\n\nSuccessful responses include the application data, current validation state, and `next_actions[]` when actions are currently available. `next_actions[].href` values point to public `/v1/enrollments` routes. Service failures (missing or malformed idempotency keys, authorization failures, invalid JSON bodies, validation errors, and service-availability errors) are returned as a top-level `errors[]` array with `code`, `message`, and optional `field`. Edge-generated failures (API Gateway and WAF) instead use the unified `error` envelope: a missing or invalid API key returns `403 forbidden`, and `413`, `415`, edge `429`, and gateway `502`/`504` also use that envelope. See the `EnrollmentError` response for both shapes.",
"operationId": "createEnrollment",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"description": "Required partner-supplied request identifier (1-255 chars, `A-Z`, `a-z`, `0-9`, `-`, `_`). Scoped by API key and retained for 24 hours.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9_\\-]{1,255}$"
}
}
],
"requestBody": {
# --- truncated at 32 KB (177 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/healthsherpa/refs/heads/main/openapi/healthsherpa-one-openapi.json