{ "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, 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. 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" }, { "name": "Policy Status" } ], "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/policy-status/applications": { "get": { "tags": [ "Policy Status" ], "summary": "List on-exchange applications for policy status readback", "description": "Alpha release: not all applications have policy status data yet, and carrier coverage is expanding, so treat missing data as expected. Approval-gated on-exchange policy status API for listing HealthSherpa Marketplace applications visible to the OAuth-linked agent. Send `exchange=on_exchange` and `plan_year` plus optional `limit` and `offset`. The `exchange` query parameter is accepted for routing context and is not forwarded to the Marketplace policy status API. This endpoint does not accept `product` or off-exchange enrollment filters; use the direct enrollment API for off-exchange applications. The response body includes application summary rows plus pagination metadata.", "operationId": "listPolicyStatusApplications", "parameters": [ { "name": "exchange", "in": "query", "required": true, "description": "Policy-status routing channel. Must be `on_exchange`.", "schema": { "type": "string", "enum": [ "on_exchange" ] } }, { "name": "plan_year", "in": "query", "required": true, "description": "Application plan year.", "schema": { "type": "integer" } }, { "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/PolicyStatusApplicationsResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "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/policy-status/applications/{confirmation_id}": { "get": { "tags": [ "Policy Status" ], "summary": "Fetch policy statuses for an on-exchange application", "description": "Alpha release: policy status fields are populated only when the carrier reports them, and carrier coverage is expanding. Approval-gated on-exchange policy status API for reading policy statuses for a HealthSherpa Marketplace application confirmation id. Send `exchange=on_exchange` and `plan_year`; the path id is the Marketplace application confirmation id returned by `GET /v1/policy-status/applications`. The `exchange` query parameter is accepted for routing context and is not forwarded to the Marketplace policy status API.", "operationId": "getPolicyStatusApplication", "parameters": [ { "name": "confirmation_id", "in": "path", "required": true, "description": "HealthSherpa Marketplace application confirmation id.", "schema": { "type": "string" } }, { "name": "exchange", "in": "query", "required": true, "description": "Policy-status routing channel. Must be `on_exchange`.", "schema": { "type": "string", "enum": [ "on_exchange" ] } }, { "name": "plan_year", "in": "query", "required": true, "description": "Application plan year.", "schema": { "type": "integer" } } ], "responses": { "200": { "$ref": "#/components/responses/PolicyStatusApplicationResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "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/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": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentRequest" }, "example": { "context": { "product": "ichra", "exchange": "off_exchange", "plan_year": 2026 }, "external_id": "crm-application-123", "plan_hios_id": "12345CO1234501", "desired_effective_date": "2026-01-01", "applicants": { "primary": { "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-01-01", "gender": "female", "email": "jane@example.com", "phone": "5551234567", "signature": "Jane Doe" } }, "residential_address": { "street_address_1": "123 Main St", "city": "Denver", "state": "CO", "zip_code": "80202" }, "special_enrollment_period": { "event_type": "offered_ichra", "event_date": "2025-12-01" } } } } }, "responses": { "200": { "$ref": "#/components/responses/EnrollmentResponse" }, "201": { "$ref": "#/components/responses/EnrollmentResponse" }, "400": { "$ref": "#/components/responses/EnrollmentError" }, "401": { "$ref": "#/components/responses/EnrollmentError" }, "403": { "$ref": "#/components/responses/EnrollmentError" }, "409": { "$ref": "#/components/responses/EnrollmentError" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$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" } } } }, "/v1/enrollments/{enrollment_id}/submissions": { "post": { "tags": [ "Enrollments" ], "summary": "Submit a direct enrollment application", "description": "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. Check `errors[]` on the application response before calling; submission fails with `422` if the application still has outstanding errors. 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.\n\nFor 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 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": "submitEnrollmentApplication", "parameters": [ { "name": "enrollment_id", "in": "path", "required": true, "description": "Application id returned by `POST /v1/enrollments`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitRequest" }, "example": { "context": { "product": "ichra", "exchange": "off_exchange" } } } } }, "responses": { "202": { "$ref": "#/components/responses/SubmitEnrollmentResponse" }, "400": { "$ref": "#/components/responses/EnrollmentError" }, "401": { "$ref": "#/components/responses/EnrollmentError" }, "403": { "$ref": "#/components/responses/EnrollmentError" }, "404": { "$ref": "#/components/responses/EnrollmentError" }, "422": { "$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" } } } }, "/v1/enrollments/{enrollment_id}/cancellations": { "post": { "tags": [ "Enrollments" ], "summary": "Cancel a direct enrollment application", "description": "Approval-gated direct enrollment API for cancelling an off-exchange application that is pending effectuation. Send the HealthSherpa ONE `context` object with `product = \"ichra\"` and `exchange = \"off_exchange\"`. Not all carriers support cancellation; check the application read response for carrier capabilities before calling. A successful response returns `202 Accepted` with the updated status-change data. 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 you do not turn an already-accepted cancellation into a misleading not-allowed/no-op retry response. Service failures use a top-level `errors[]` array with `code`, `message`, and optional `field`; cancellation-not-allowed responses use `400 invalid_field_value`. Failures blocked at the API edge use the unified `error` envelope.", "operationId": "cancelEnrollmentApplication", "parameters": [ { "name": "enrollment_id", "in": "path", "required": true, "description": "Application id returned by `POST /v1/enrollments`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentActionContextRequest" }, "example": { "context": { "product": "ichra", "exchange": "off_exchange" } } } } }, "responses": { "202": { "$ref": "#/components/responses/EnrollmentStatusChangeResponse" }, "400": { "$ref": "#/components/responses/EnrollmentError" }, "401": { "$ref": "#/components/responses/EnrollmentError" }, "403": { "$ref": "#/components/responses/EnrollmentError" }, "404": { "$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" } } } }, "/v1/enrollments/{enrollment_id}/terminations": { "post": { "tags": [ "Enrollments" ], "summary": "Terminate an active policy", "description": "Approval-gated direct enrollment API for terminating an active off-exchange policy before its natural expiration date. Send the HealthSherpa ONE `context` object with `product = \"ichra\"` and `exchange = \"off_exchange\"`. Not all carriers support termination; check the application read response for carrier capabilities before calling. A successful response returns `202 Accepted` with the updated status-change data. 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 you do not turn an already-accepted termination into a misleading not-allowed/no-op retry response. Service failures use a top-level `errors[]` array with `code`, `message`, and optional `field`; termination-not-allowed responses use `400 invalid_field_value`. Failures blocked at the API edge use the unified `error` envelope.", "operationId": "terminateEnrollmentApplication", "parameters": [ { "name": "enrollment_id", "in": "path", "required": true, "description": "Application id returned by `POST /v1/enrollments`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentActionContextRequest" }, "example": { "context": { "product": "ichra", "exchange": "off_exchange" } } } } }, "responses": { "202": { "$ref": "#/components/responses/EnrollmentStatusChangeResponse" }, "400": { "$ref": "#/components/responses/EnrollmentError" }, "401": { "$ref": "#/components/responses/EnrollmentError" }, "403": { "$ref": "#/components/responses/EnrollmentError" }, "404": { "$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" } } } }, "/v1/enrollments/{enrollment_id}/payment_redirect": { "get": { "tags": [ "Enrollments" ], "summary": "Get payment redirect data", "description": "Approval-gated direct enrollment API for retrieving the carrier payment redirect data for an off-exchange application. Send `product=ichra` and `exchange=off_exchange` as required query parameters so HealthSherpa ONE can validate the direct-enrollment routing channel. Use this when the application response includes `payment_instructions.payment_redirect_supported = true`.\n\nThe response includes the carrier endpoint URL, the HTTP method, and form fields to submit in the shopper's browser. The keys and values in `fields` vary by carrier. Do not interpret, filter, rename, or modify them; include every returned field exactly as provided as hidden inputs in a form POST to `endpoint`. 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": "getEnrollmentPaymentRedirect", "parameters": [ { "name": "enrollment_id", "in": "path", "required": true, "description": "Application id returned by `POST /v1/enrollments`.", "schema": { "type": "string" } }, { "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" ] } } ], "responses": { "200": { "$ref": "#/components/responses/PaymentRedirectResponse" }, "401": { "$ref": "#/components/responses/EnrollmentError" }, "403": { "$ref": "#/components/responses/EnrollmentError" }, "404": { "$ref": "#/components/responses/EnrollmentError" }, "422": { "$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" } } } }, "/v1/enrollments/{enrollment_id}/supporting_documentation": { "post": { "tags": [ "Enrollments" ], "summary": "Upload supporting documentation", "description": "Approval-gated direct enrollment API for uploading a document that supports SEP eligibility for an off-exchange application. Some carriers require documentation for certain SEP reasons before coverage is effectuated. Use `GET /v1/enrollments/{enrollment_id}?product=ichra&exchange=off_exchange` to check `document_status`.\n\nSend the HealthSherpa ONE `context` object with `product = \"ichra\"` and `exchange = \"off_exchange\"` plus either `multipart/form-data` with a binary `file`, or `application/json` with the same file bytes in `file.content_base64`. HealthSherpa ONE does not persist the uploaded file after processing. 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": "uploadEnrollmentSupportingDocumentation", "parameters": [ { "name": "enrollment_id", "in": "path", "required": true, "description": "Application id returned by `POST /v1/enrollments`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "context", "file", "document_type" ], "properties": { "context": { "$ref": "#/components/schemas/EnrollmentActionContext" }, "file": { "type": "string", "format": "binary", "description": "The document file. Supported formats are PDF, JPEG, and PNG." }, "document_type": { "type": "string", "enum": [ "sep" ], "description": "Type of supporting document. Currently only `sep` is accepted." } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentationRequest" }, "example": { "context": { "product": "ichra", "exchange": "off_exchange" }, "file": { "filename": "sep-proof.pdf", "content_type": "application/pdf", "content_base64": "JVBERi0xLjQg..." }, "document_type": "sep" } } } }, "responses": { "200": { "$ref": "#/components/responses/SupportingDocumentationResponse" }, "201": { "$ref": "#/components/responses/SupportingDocumentationResponse" }, "400": { "$ref": "#/components/responses/EnrollmentError" }, "401": { "$ref": "#/components/responses/EnrollmentError" }, "403": { "$ref": "#/components/responses/EnrollmentError" }, "404": { "$ref": "#/components/responses/EnrollmentError" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$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" } } } }, "/v1/enrollments/{enrollment_id}": { "get": { "tags": [ "Enrollments" ], "summary": "Fetch a direct enrollment application", "description": "Approval-gated direct enrollment API for reading an application. Send `product=ichra` and `exchange=off_exchange` as required query parameters so HealthSherpa ONE can validate the direct-enrollment routing channel. HealthSherpa ONE returns the application details for the supplied id. `product` and `exchange` are the only supported read query parameters; `include_events`, `plan_year`, and other read-time query parameters are not supported. The application plan year is returned in the response. Service failures (authorization failures, invalid routing context, 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 gateway `502`/`504` also use that envelope. See the `EnrollmentError` response for both shapes.", "operationId": "getEnrollment", "parameters": [ { "name": "enrollment_id", "in": "path", "required": true, "description": "Application id returned by `POST /v1/enrollments`.", "schema": { "type": "string" } }, { "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" ] } } ], "responses": { "200": { "$ref": "#/components/responses/EnrollmentResponse" }, "400": { "$ref": "#/components/responses/EnrollmentError" }, "401": { "$ref": "#/components/responses/EnrollmentError" }, "403": { "$ref": "#/components/responses/EnrollmentError" }, "404": { "$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" } } }, "put": { "tags": [ "Enrollments" ], "summary": "Update a direct enrollment application", "description": "Approval-gated direct enrollment API for updating an off-exchange application. Treat `PUT` as a full replacement-style update. Send the HealthSherpa ONE `context` object with `product = \"ichra\"`, `exchange = \"off_exchange\"`, and `plan_year` plus the full current application payload, including unchanged fields you want to preserve. 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 here. 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, carriers may restrict updates; 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 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 updated application data and current validation state. Service failures (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": "updateEnrollment", "parameters": [ { "name": "enrollment_id", "in": "path", "required": true, "description": "Application id returned by `POST /v1/enrollments`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentUpdateRequest" }, "example": { "context": { "product": "ichra", "exchange": "off_exchange", "plan_year": 2026 }, "applicants": { "primary": { "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-01-01", "gender": "female", "us_citizen": true, "resides_in_state": true, "uses_tobacco": false, "language_spoken": "english", "language_written": "english", "email": "jane.updated@example.com", "phone": "5559876543", "signature": "Jane Doe" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/EnrollmentResponse" }, "400": { "$ref": "#/components/responses/EnrollmentError" }, "401": { "$ref": "#/components/responses/EnrollmentError" }, "403": { "$ref": "#/components/responses/EnrollmentError" }, "404": { "$ref": "#/components/responses/EnrollmentError" }, "409": { "$ref": "#/components/responses/EnrollmentError" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$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" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "responses": { "EnrollmentResponse": { "description": "Successful direct enrollment application response. The response object is additive and may include carrier-specific fields.", "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" ] } }, "Retry-After": { "description": "Returned when a retry window is available.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentResponse" }, "example": { "application_id": "HSA000000001", "external_id": "crm-application-123", "policy_status": "draft", "document_status": "none_needed", "plan_hios_id": "12345CO1234501", "plan_year": 2026, "payment_instructions": { "payment_required_with_submission": false, "payment_redirect_supported": true, "pay_by_phone_supported": false, "payment_phone_number": null }, "errors": [] } } } }, "EnrollmentListResponse": { "description": "Paginated direct enrollment application list.", "headers": { "X-Request-Id": { "description": "HealthSherpa ONE request id for tracing and support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Returned when a retry window is available.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationListResponse" }, "example": { "applications": [ { "application_id": "HSA000000001", "external_id": "crm-application-123", "employer_external_id": "employer-456", "plan_year": "2026", "plan_hios_id": "12345CO1234501", "exchange_type": "off_exchange", "policy_status": "effectuated", "created_at": "2026-01-02T10:00:00Z", "updated_at": "2026-01-03T10:00:00Z" } ], "pagination": { "limit": 25, "offset": 0, "total": 1 } } } } }, "SubmitEnrollmentResponse": { "description": "Application submission accepted. Processing can continue asynchronously; poll the application read endpoint for final policy status.", "headers": { "X-Request-Id": { "description": "HealthSherpa ONE request id for tracing and support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Returned when a retry window is available.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" }, "example": { "application_id": "HSA000000001", "external_id": "crm-application-123", "plan_year": 2026, "plan_hios_id": "12345CO1234501", "policy_status": "pending_effectuation", "payment_instructions": { "payment_required_with_submission": false, "payment_redirect_supported": true, "pay_by_phone_supported": false, "payment_phone_number": null }, "submitted_at": "2026-01-14T16:00:00Z" } } } }, "EnrollmentStatusChangeResponse": { "description": "Application status-change request accepted.", "headers": { "X-Request-Id": { "description": "HealthSherpa ONE request id for tracing and support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Returned when a retry window is available.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusChangeResponse" }, "example": { "application_id": "HSA000000001", "policy_status": "cancelled", "effective_date": "2026-02-01", "updated_at": "2026-01-14T16:10:00Z" } } } }, "PaymentRedirectResponse": { "description": "Payment redirect data returned. Render a browser form POST to `endpoint` with every returned `fields[]` entry as a hidden input.", "headers": { "X-Request-Id": { "description": "HealthSherpa ONE request id for tracing and support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Returned when a retry window is available.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRedirectResponse" }, "example": { "application_id": "HSA000000001", "method": "POST", "endpoint": "https://carrier.example.com/pay", "fields": [ { "name": "SAMLResponse", "value": "opaque-carrier-token" }, { "name": "RelayState", "value": "return-to-carrier" } ] } } } }, "SupportingDocumentationResponse": { "description": "Supporting document upload response.", "headers": { "X-Request-Id": { "description": "HealthSherpa ONE request id for tracing and support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Returned when a retry window is available.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentationResponse" }, "example": { "document_id": "DOC000000001", "application_id": "HSA000000001", "filename": "sep-proof.pdf", "document_type": "sep_verification", "uploaded_at": "2026-01-14T16:05:00Z" } } } }, "PolicyStatusApplicationsResponse": { "description": "On-exchange Marketplace applications available for policy status readback.", "headers": { "X-Request-Id": { "description": "HealthSherpa ONE request id for tracing and support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Returned when a retry window is available.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyStatusApplicationsResponse" }, "example": { "applications": [ { "confirmation_id": "HSA123456789", "external_id": "crm-application-123", "plan_year": 2026, "exchange_type": "on_exchange" } ], "pagination": { "limit": 25, "offset": 0 } } } } }, "PolicyStatusApplicationResponse": { "description": "Policy statuses for one on-exchange Marketplace application.", "headers": { "X-Request-Id": { "description": "HealthSherpa ONE request id for tracing and support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Returned when a retry window is available.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyStatusApplicationResponse" }, "example": { "policy_statuses": [ { "exchange_assigned_policy_id": "POL123", "issuer_hios_id": "12345", "effective_date": "2026-01-01", "status": "active", "payment_status": "paid", "current_balance_cents": 0, "past_due_balance_cents": 0, "paid_through_date": "2026-01-31", "grace_period_start_date": null, "updated_at": "2026-01-15T12:00:00Z" } ] } } } }, "EnrollmentError": { "description": "A direct enrollment error response. The body comes in one of two shapes depending on where the failure is generated:\n\n- **Service failures** use the top-level `errors[]` shape (`EnrollmentErrorsResponse`). This covers request validation, idempotency-key handling, authorization, service availability, and application-level errors.\n- **Edge-generated failures** (API Gateway and WAF, before the request reaches the service) use the unified `error` envelope (`ErrorResponse`). This is what you receive for a missing or invalid API key (`403 forbidden`), payload-size and media-type rejections (`413`, `415`), edge rate limiting (`429`), and gateway-level `5xx`.\n\nBranch on the presence of `errors` vs `error`, and on the `code` value, rather than on HTTP status alone.", "headers": { "X-Request-Id": { "description": "HealthSherpa ONE request id for tracing and support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Returned when a retry window is available.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EnrollmentErrorsResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "service_errors": { "summary": "Service failure (errors[])", "value": { "errors": [ { "code": "plan_not_available", "field": "plan_hios_id", "message": "Plan is not available for the requested effective date" } ] } }, "edge_error": { "summary": "Edge-generated failure (unified error envelope)", "value": { "error": { "code": "forbidden", "message": "The supplied API key is missing, invalid, or not authorized for this API." } } } } } } }, "BadRequest": { "description": "Request validation failed. The response body's `error.details` map contains per-field messages when the backend produced the error; edge-generated 400s omit `details`.\n\nA malformed `Idempotency-Key` header is also rejected here with `code: idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "invalid_request", "message": "Validation failed.", "details": { "zip_code": ["ZIP code must be 5 digits"] } } } } } }, "IdempotencyInProgress": { "description": "A previous request with the same `Idempotency-Key` is still being processed by the API. The partner should wait briefly and retry. The response is not produced by the upstream service — the in-flight request from the first call will succeed or fail on its own.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is already being processed. Retry once it completes." } } } } }, "IdempotencyMismatch": { "description": "The `Idempotency-Key` has been used before within the 24-hour retention window, but the current request body is not byte-for-byte identical to the original. To resolve, either resubmit the exact original payload or generate a fresh `Idempotency-Key` for the new request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "idempotency_mismatch", "message": "This Idempotency-Key has already been used with a different request body." } } } } }, "Forbidden": { "description": "The API key is missing, invalid, not authorized for this API, or the request was blocked at the API edge. Public API requests may receive this edge-generated response before the backend can return a runtime 401. When a request reaches the backend, 403 may also mean the developer account or integration is not in the state required for that operation. For `POST /v1/enrollment-sessions`, that operation documents its own flow-scoped 403 requirements (both flows require approved on-exchange enrollment access, plus `agent_assisted` OAuth link vs `self_service` deeplink agent ID) instead of using this shared response reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "forbidden", "message": "The supplied API key is missing, invalid, or not authorized for this API." } } } } }, "NotFound": { "description": "The requested resource could not be found. Emitted by the backend when no supported data matches the request (for example, no counties for a ZIP), and by the API edge for unknown paths.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "No counties found for ZIP 12345." } } } } }, "PayloadTooLarge": { "description": "The request body exceeded the maximum size accepted by the API edge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "payload_too_large", "message": "The request payload exceeded the maximum allowed size." } } } } }, "UnsupportedMediaType": { "description": "The request `Content-Type` is not supported by the endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unsupported_media_type", "message": "The request Content-Type is not supported by this endpoint." } } } } }, "RateLimited": { "description": "Rate limit exceeded. Clients should back off and retry after the delay advertised in the Retry-After header.", "headers": { "Retry-After": { "description": "Number of seconds the client should wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "Request rate limit exceeded. Please slow down and retry shortly." } } } } }, "InternalError": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred." } } } } }, "BadGateway": { "description": "The API edge received an invalid response from the backend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "bad_gateway", "message": "The API edge received an invalid response from the backend. Please try again later." } } } } }, "ServiceUnavailable": { "description": "The API is temporarily unable to serve the request. This may be returned by the API edge when the backend is unhealthy, or by the backend when an upstream catalog, quoting, or lookup service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later." } } } } }, "GatewayTimeout": { "description": "The API edge did not receive a timely response from the backend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "gateway_timeout", "message": "The API edge did not receive a timely response from the backend. Please try again later." } } } } } }, "schemas": { "PingResponse": { "type": "object", "additionalProperties": true, "required": [ "environment", "ok" ], "properties": { "environment": { "type": "string" }, "ok": { "type": "boolean" } } }, "EnrollmentRequest": { "description": "HealthSherpa ONE direct enrollment create request. Send the application payload at the request root and include the HealthSherpa ONE `context` object for routing. 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.", "allOf": [ { "$ref": "#/components/schemas/ApplicationCreateRequest" }, { "type": "object", "additionalProperties": true, "required": [ "context" ], "properties": { "context": { "$ref": "#/components/schemas/EnrollmentContext" } }, "not": { "anyOf": [ { "required": [ "agent_of_record" ] }, { "required": [ "_agent_id" ] }, { "required": [ "tpa_slug" ] }, { "required": [ "actor" ], "properties": { "actor": { "type": "object", "required": [ "agent_id" ] } } } ] } } ] }, "EnrollmentUpdateRequest": { "type": "object", "description": "HealthSherpa ONE direct enrollment update request. Treat `PUT` as a full replacement-style update. Send the HealthSherpa ONE `context` object with `product = \"ichra\"`, `exchange = \"off_exchange\"`, and `plan_year` plus the full current application payload, including unchanged fields you want to preserve. When `applicants.primary` is present, include the full current primary applicant object because omitted primary fields may be cleared. HealthSherpa ONE maps `context.plan_year` to the application `plan_year`, applies `_agent_id` and `tpa_slug` from your account setup, and rejects caller-supplied `_agent_id`, `tpa_slug`, `actor.agent_id`, and `agent_of_record`.", "additionalProperties": true, "required": [ "context" ], "properties": { "context": { "$ref": "#/components/schemas/EnrollmentUpdateContext" }, "applicants": { "$ref": "#/components/schemas/Applicants", "description": "Applicant objects are replacement-shaped. When sending `applicants.primary`, include the full current primary applicant object; omitted primary fields may be cleared." } }, "not": { "anyOf": [ { "required": [ "agent_of_record" ] }, { "required": [ "_agent_id" ] }, { "required": [ "tpa_slug" ] }, { "required": [ "actor" ], "properties": { "actor": { "type": "object", "required": [ "agent_id" ] } } } ] } }, "SupportingDocumentationRequest": { "type": "object", "description": "Supporting document upload request for SEP verification. JSON requests send base64-encoded file bytes; multipart requests send the binary file directly. HealthSherpa ONE validates `context` and processes only the documented upload fields.", "required": [ "context", "file", "document_type" ], "properties": { "context": { "$ref": "#/components/schemas/EnrollmentActionContext" }, "file": { "type": "object", "required": [ "filename", "content_type", "content_base64" ], "properties": { "filename": { "type": "string", "example": "sep-proof.pdf" }, "content_type": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png" ], "description": "MIME type of the uploaded file.", "example": "application/pdf" }, "content_base64": { "type": "string", "format": "byte", "description": "Base64-encoded file bytes.", "example": "JVBERi0xLjQg..." } } }, "document_type": { "type": "string", "enum": [ "sep" ], "description": "Type of supporting document. Currently only `sep` is accepted." } } }, "EnrollmentActionContextRequest": { "type": "object", "description": "Routing context for direct enrollment action endpoints.", "additionalProperties": true, "required": [ "context" ], "properties": { "context": { "$ref": "#/components/schemas/EnrollmentActionContext" } } }, "EnrollmentActionContext": { "type": "object", "additionalProperties": true, "required": [ "product", "exchange" ], "properties": { "product": { "type": "string", "enum": [ "ichra" ] }, "exchange": { "type": "string", "enum": [ "off_exchange" ] } } }, "SubmitResponse": { "type": "object", "description": "Response returned when an application submission is accepted. The object is additive and may include carrier-specific fields.", "additionalProperties": true, "properties": { "application_id": { "type": "string", "description": "Application that was submitted." }, "external_id": { "type": "string", "description": "Partner-supplied external application id when available." }, "plan_year": { "type": "integer" }, "plan_hios_id": { "type": "string" }, "policy_status": { "type": "string", "description": "Status after accepting the submission. Submission processing may continue asynchronously; poll the application read endpoint for the final outcome." }, "payment_instructions": { "$ref": "#/components/schemas/PaymentInstructions" }, "submitted_at": { "type": "string", "format": "date-time", "description": "When the application was submitted to the carrier." } } }, "ApplicationListResponse": { "type": "object", "description": "Paginated list of direct enrollment applications.", "additionalProperties": true, "required": [ "applications", "pagination" ], "properties": { "applications": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationListItem" } }, "pagination": { "$ref": "#/components/schemas/ApplicationListPagination" } } }, "ApplicationListItem": { "type": "object", "description": "Summary application row returned by `GET /v1/enrollments`.", "additionalProperties": true, "properties": { "application_id": { "type": "string" }, "external_id": { "type": "string" }, "employer_external_id": { "type": "string" }, "plan_year": { "type": "string", "description": "Application plan year." }, "plan_hios_id": { "type": "string" }, "exchange_type": { "type": "string" }, "policy_status": { "type": "string", "enum": [ "draft", "pending_effectuation", "effectuated", "submission_failed", "cancelled", "terminated" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PolicyStatusApplicationListItem": { "type": "object", "description": "On-exchange Marketplace application summary row returned by `GET /v1/policy-status/applications`.", "additionalProperties": true, "properties": { "confirmation_id": { "type": "string", "description": "HealthSherpa Marketplace application confirmation id." }, "external_id": { "type": [ "string", "null" ], "description": "Partner-supplied external application id when available." }, "plan_year": { "type": "integer", "description": "Application plan year." }, "exchange_type": { "type": [ "string", "null" ], "description": "Marketplace exchange type returned by the upstream policy status API when available." } } }, "PolicyStatusApplicationsResponse": { "type": "object", "description": "On-exchange Marketplace applications available for policy status readback.", "additionalProperties": true, "required": [ "applications", "pagination" ], "properties": { "applications": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyStatusApplicationListItem" } }, "pagination": { "$ref": "#/components/schemas/PolicyStatusApplicationPagination" } } }, "PolicyStatusApplicationPagination": { "type": "object", "description": "Pagination metadata returned by the Marketplace policy status API.", "additionalProperties": true, "required": [ "limit", "offset" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "PolicyStatusApplicationResponse": { "type": "object", "description": "Policy statuses for one on-exchange Marketplace application.", "additionalProperties": true, "required": [ "policy_statuses" ], "properties": { "policy_statuses": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyStatusItem" } } } }, "PolicyStatusItem": { "type": "object", "description": "Marketplace policy status row for one policy attached to an application.", "additionalProperties": true, "properties": { "exchange_assigned_policy_id": { "type": [ "string", "null" ] }, "issuer_hios_id": { "type": [ "string", "null" ] }, "effective_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": [ "string", "null" ] }, "payment_status": { "type": [ "string", "null" ] }, "current_balance_cents": { "type": [ "integer", "null" ], "description": "Current balance in cents when returned by the Marketplace policy status API." }, "past_due_balance_cents": { "type": [ "integer", "null" ], "description": "Past-due balance in cents when returned by the Marketplace policy status API." }, "paid_through_date": { "type": [ "string", "null" ], "format": "date" }, "grace_period_start_date": { "type": [ "string", "null" ], "format": "date" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ApplicationListPagination": { "type": "object", "description": "Pagination metadata for application list responses.", "additionalProperties": true, "required": [ "limit", "offset", "total" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } }, "StatusChangeResponse": { "type": "object", "description": "Response returned for an accepted application cancellation or termination status change.", "additionalProperties": true, "required": [ "application_id", "policy_status", "updated_at" ], "properties": { "application_id": { "type": "string", "description": "Application whose policy status changed." }, "policy_status": { "type": "string", "description": "Updated policy status." }, "effective_date": { "type": [ "string", "null" ], "format": "date", "description": "The effective date of the status change when present." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the status-change request updated the application." } } }, "SubmitRequest": { "type": "object", "description": "Routing context for direct enrollment submission. HealthSherpa ONE uses this context to validate the off-exchange direct-enrollment channel. `plan_year` is not required for submission.", "additionalProperties": true, "required": [ "context" ], "properties": { "context": { "type": "object", "additionalProperties": true, "required": [ "product", "exchange" ], "properties": { "product": { "type": "string", "enum": [ "ichra" ] }, "exchange": { "type": "string", "enum": [ "off_exchange" ] } } } } }, "SupportingDocumentationResponse": { "type": "object", "additionalProperties": true, "properties": { "document_id": { "type": "string", "description": "Identifier assigned to the uploaded document." }, "application_id": { "type": "string", "description": "Application this document is attached to." }, "filename": { "type": "string" }, "document_type": { "type": "string", "description": "Type of supporting document." }, "uploaded_at": { "type": "string", "format": "date-time", "description": "When the document was received." } } }, "PaymentRedirectResponse": { "type": "object", "additionalProperties": true, "required": [ "application_id", "method", "endpoint", "fields" ], "properties": { "application_id": { "type": "string", "description": "Application id returned by `POST /v1/enrollments`." }, "method": { "type": "string", "description": "HTTP method to use. Always `POST`.", "enum": [ "POST" ] }, "endpoint": { "type": "string", "format": "uri", "description": "The carrier payment URL. Submit the form POST to this URL." }, "fields": { "type": "array", "description": "Form fields to include as hidden inputs in the POST to `endpoint`. The fields vary by carrier payment integration. Include every returned field exactly as provided; do not filter, rename, or modify entries.", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The form field name." }, "value": { "type": "string", "description": "The form field value." } } } } } }, "EnrollmentUpdateContext": { "type": "object", "description": "Routing context for direct enrollment updates. Send `product = ichra`, `exchange = off_exchange`, and `plan_year`; `plan_year` is mapped to the application plan year.", "additionalProperties": true, "required": [ "product", "exchange", "plan_year" ], "properties": { "product": { "type": "string", "enum": [ "ichra" ] }, "exchange": { "type": "string", "enum": [ "off_exchange" ] }, "plan_year": { "type": "integer", "minimum": 2020, "maximum": 2099 } } }, "EnrollmentContext": { "type": "object", "description": "Routing context for direct enrollment create requests. Direct enrollment currently supports only `product = ichra` and `exchange = off_exchange`. Use `POST /v1/enrollment-sessions` for on-exchange enrollment.", "additionalProperties": true, "required": [ "product", "exchange", "plan_year" ], "properties": { "product": { "type": "string", "enum": [ "ichra" ] }, "exchange": { "type": "string", "enum": [ "off_exchange" ] }, "coverage_family": { "type": "string", "enum": [ "medical" ] }, "coverage_type": { "type": "string", "enum": [ "medical" ] }, "plan_year": { "type": "integer", "minimum": 2020, "maximum": 2099 } } }, "ApplicationCreateRequest": { "type": "object", "description": "Canonical application schema accepted by `POST /v1/enrollments` alongside the HealthSherpa ONE `context` object. HealthSherpa ONE derives the application `plan_year` from `context.plan_year`; do not send a root `plan_year` in requests. Carrier-specific submission-readiness requirements are returned in the successful response `errors[]` array. HealthSherpa ONE applies `_agent_id` and `tpa_slug` from your account setup and rejects caller-supplied `_agent_id`, `tpa_slug`, `actor.agent_id`, and `agent_of_record`.", "additionalProperties": true, "required": [ "plan_hios_id", "applicants", "residential_address" ], "properties": { "external_id": { "type": "string", "description": "Your unique identifier for this application. When omitted, HealthSherpa ONE defaults it to the request's `Idempotency-Key`." }, "_agent_id": { "type": [ "string", "null" ], "description": "Server-owned HealthSherpa agent identifier. Do not send this field; caller-supplied values return `400 invalid_request`." }, "tpa_slug": { "type": "string", "description": "Server-owned HealthSherpa TPA identifier. Do not send this field; caller-supplied values return `400 invalid_request`." }, "agent_of_record": { "$ref": "#/components/schemas/AgentOfRecord", "deprecated": true, "description": "Not accepted by HealthSherpa ONE. The connected HealthSherpa agent is the agent of record; caller-supplied `agent_of_record` returns `400 invalid_request`." }, "plan_hios_id": { "type": "string", "description": "14-character HIOS plan ID." }, "plan_year": { "type": "integer", "description": "Plan year for the application. Omit this root field; HealthSherpa ONE sets it from `context.plan_year`." }, "desired_effective_date": { "type": "string", "format": "date", "description": "Optional. When omitted, the carrier auto-determines the effective date based on the SEP type and event date. When provided, the date must be valid for the SEP reason and event date. Invalid dates return `422` with valid choices when available, or a message that effective-date selection is unavailable. There is no endpoint to query valid dates ahead of time." }, "applicants": { "$ref": "#/components/schemas/Applicants" }, "residential_address": { "$ref": "#/components/schemas/Address" }, "mailing_address": { "$ref": "#/components/schemas/MailingAddress" }, "hra": { "$ref": "#/components/schemas/HRA" }, "special_enrollment_period": { "$ref": "#/components/schemas/SpecialEnrollmentPeriod" }, "attestations": { "$ref": "#/components/schemas/Attestations" }, "signatures": { "$ref": "#/components/schemas/Signatures" }, "communication_preferences": { "$ref": "#/components/schemas/CommunicationPreferences" }, "american_indian_or_alaskan_native_in_household": { "type": "boolean" }, "analytics": { "$ref": "#/components/schemas/Analytics" } } }, "AgentOfRecord": { "type": "object", "description": "Agent-of-record payload. HealthSherpa ONE does not accept caller-supplied agent-of-record data on `POST /v1/enrollments`; attribution is derived from your approved account setup.", "additionalProperties": true, "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "national_producer_number": { "type": "string", "description": "1-10 digits, must not start with 0." }, "carrier_producer_code": { "type": "string", "description": "Carrier-specific agent identifier. For Elevance, this is the 10-character uppercase string they generate, ending in Y or Z." }, "state_license_number": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "fax_number": { "type": "string" }, "address": { "$ref": "#/components/schemas/SimpleAddress" }, "signature": { "type": "string" } } }, "SimpleAddress": { "type": "object", "additionalProperties": true, "properties": { "street_address_1": { "type": "string" }, "street_address_2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" } } }, "Applicants": { "type": "object", "additionalProperties": true, "required": [ "primary" ], "properties": { "primary": { "$ref": "#/components/schemas/PrimaryApplicant" }, "dependents": { "type": "array", "items": { "$ref": "#/components/schemas/Dependent" } } } }, "PrimaryApplicant": { "allOf": [ { "$ref": "#/components/schemas/ApplicantBase" }, { "type": "object", "required": [ "first_name", "last_name", "date_of_birth", "gender" ], "properties": { "phone_type": { "type": "string", "enum": [ "home", "work", "cell" ] }, "secondary_phone": { "type": "string", "description": "Secondary contact phone number." }, "guardian": { "$ref": "#/components/schemas/Guardian" }, "responsible_party": { "$ref": "#/components/schemas/ResponsibleParty" }, "translator": { "$ref": "#/components/schemas/Translator" }, "signature": { "type": "string", "description": "Primary applicant's typed full legal name. Required for submission. This field is on the applicant object, not under the top-level `signatures` object." }, "children_live_with_primary": { "type": "boolean" }, "has_pediatric_dental_coverage": { "type": "boolean" }, "previously_applied": { "type": "boolean" }, "previously_applied_member_id": { "type": "string" }, "primary_requesting_coverage": { "type": "boolean", "description": "Whether the primary applicant is requesting coverage for themselves." } } } ] }, "Dependent": { "allOf": [ { "$ref": "#/components/schemas/ApplicantBase" }, { "type": "object", "required": [ "first_name", "last_name", "date_of_birth", "gender", "relationship" ], "properties": { "gender": { "type": "string", "enum": [ "male", "female" ], "description": "Dependent applicant gender." }, "relationship": { "type": "string", "enum": [ "spouse", "domestic_partner", "child", "parent", "stepparent", "parent_in_law", "sibling", "other" ], "description": "`spouse`, `domestic_partner`, and `child` are supported by all carriers. Other values are accepted by select carriers and states." }, "alternate_address": { "$ref": "#/components/schemas/AlternateAddress" }, "guardian": { "$ref": "#/components/schemas/Guardian" } } } ] }, "ApplicantBase": { "type": "object", "additionalProperties": true, "properties": { "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "suffix": { "type": "string", "enum": [ "Jr.", "Sr.", "II", "III", "IV", "V" ] }, "ssn": { "type": "string", "description": "9 digits, no dashes. Encrypted at rest." }, "itin": { "type": "string", "description": "Individual Taxpayer Identification Number. Alternative to SSN." }, "date_of_birth": { "type": "string", "format": "date" }, "gender": { "type": "string", "enum": [ "male", "female", "x" ], "description": "`male` and `female` are accepted by all carriers. `x` is accepted for New York applicants; carriers in other states reject `x` at submission." }, "married": { "type": "boolean" }, "us_citizen": { "type": "boolean" }, "resides_in_state": { "type": "boolean" }, "uses_tobacco": { "type": "boolean", "description": "Tobacco use in the last 6 months." }, "tobacco_not_applicable": { "type": "boolean", "description": "Set to `true` if tobacco question is not applicable for this applicant." }, "race_ethnicity": { "type": "string", "enum": [ "white", "black_or_african_american", "american_indian_or_alaskan_native", "asian_indian", "chinese", "filipino", "japanese", "korean", "vietnamese", "native_hawaiian", "guamanian_or_chamorro", "samoan", "decline_to_answer" ], "description": "Required by some carriers. Use `decline_to_answer` if not collected." }, "hispanic_origin": { "type": "string", "enum": [ "yes", "no", "decline_to_answer" ], "description": "Required by some carriers. Use `decline_to_answer` if not collected." }, "hispanic_origin_description": { "type": "string", "enum": [ "cuban", "mexican_mexican_american_or_chicanx", "puerto_rican", "other_hispanic_latino_or_spanish_origin", "decline_to_answer" ], "description": "Required when `hispanic_origin` is `yes`." }, "language_spoken": { "$ref": "#/components/schemas/ApplicantLanguage" }, "language_written": { "$ref": "#/components/schemas/ApplicantLanguage" }, "external_id": { "type": "string", "description": "Your identifier for this member." }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "full_time_student": { "type": "boolean" }, "graduation_date": { "type": "string", "format": "date", "description": "Required if `full_time_student` is `true`." }, "marital_status": { "type": "string", "description": "Carrier-specific marital status. When provided, takes precedence over the `married` boolean." }, "has_disability": { "type": "boolean", "description": "Affects dependent age eligibility limits." }, "disability_is_temporary": { "type": "boolean", "description": "Whether the disability is temporary. Only accepted by carriers that require disability follow-up questions." }, "disability_end_date": { "type": "string", "format": "date", "description": "Expected end date of a temporary disability. Only accepted by carriers that require disability follow-up questions." }, "medicare_medicaid_eligible": { "type": "boolean", "description": "Whether the applicant is eligible for Medicare or Medicaid. Only accepted by carriers that require this field." }, "medicare_eligible": { "type": "boolean", "description": "Whether the applicant is eligible for Medicare." }, "enrolled_in_medicare": { "type": "boolean" }, "enrolled_in_medicare_parts_a_or_b": { "type": "boolean" }, "enrolled_in_medicaid_chip_or_other_gov_program": { "type": "boolean" }, "veteran_or_active_duty_military": { "type": "boolean" }, "currently_incarcerated": { "type": "boolean" }, "has_eligible_immigration_status": { "type": "boolean" }, "existing_coverage": { "$ref": "#/components/schemas/ExistingCoverage" }, "add_to_donate_life_registry": { "type": "boolean", "description": "Whether the applicant wants to be added to the Donate Life registry. Only accepted by carriers that support this field." } } }, "ApplicantLanguage": { "type": "string", "enum": [ "english", "spanish", "arabic", "chinese", "french_creole", "french", "german", "gujarati", "hindi", "korean", "polish", "portuguese", "russian", "tagalog", "urdu", "vietnamese", "other" ] }, "ExistingCoverage": { "type": "object", "additionalProperties": true, "properties": { "has_existing_coverage": { "type": "boolean" }, "plan_replaces_existing_coverage": { "type": "boolean" }, "type": { "type": "string", "enum": [ "issuer", "government" ], "description": "`issuer`: coverage with another issuer. `government`: government program such as Medicare or Medicaid." }, "insurer": { "type": "string" }, "policy_id": { "type": "string" }, "policyholder_name": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "term_date": { "type": "string", "format": "date" }, "will_continue": { "type": "boolean", "description": "Whether the existing coverage will continue alongside the new plan." } } }, "Guardian": { "type": "object", "description": "Required for primary applicants under 18.", "additionalProperties": true, "properties": { "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "suffix": { "type": "string", "enum": [ "Jr.", "Sr.", "II", "III", "IV", "V" ] }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "relationship": { "type": "string", "enum": [ "parent", "legal_guardian", "grandparent", "other" ] }, "date_of_birth": { "type": "string", "format": "date" }, "relationship_other": { "type": "string", "description": "Required if `relationship` is `other`." }, "email": { "type": "string", "format": "email" }, "home_phone": { "type": "string" }, "alternate_phone": { "type": "string" }, "mailing_address": { "type": "object", "additionalProperties": true, "description": "Guardian's mailing address, if different from the applicant's residential address.", "properties": { "street_address_1": { "type": "string" }, "street_address_2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "fips_code": { "type": "string" } } } } }, "ResponsibleParty": { "type": "object", "description": "Responsible party for a minor applicant, when someone other than the guardian is financially responsible. Required by Security Health, Sanford, Oscar, and UHC.", "additionalProperties": true, "properties": { "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "sex": { "type": "string", "enum": [ "male", "female" ] }, "relationship": { "type": "string", "enum": [ "parent_guardian", "sibling" ] }, "phone": { "type": "string" }, "street_address_1": { "type": "string" }, "street_address_2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" } } }, "Translator": { "type": "object", "description": "Translator assisting the applicant. Required by some carriers when the applicant requires language assistance.", "additionalProperties": true, "properties": { "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "reason": { "type": "string", "description": "Why a translator is needed." } } }, "AlternateAddress": { "type": "object", "description": "Address for a dependent living at a different address than the primary applicant.", "additionalProperties": true, "properties": { "street_address_1": { "type": "string" }, "street_address_2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "fips_code": { "type": "string" }, "reason": { "type": "string", "description": "Reason the dependent has a different address." } } }, "Address": { "type": "object", "additionalProperties": true, "required": [ "street_address_1", "city", "state", "zip_code" ], "properties": { "street_address_1": { "type": "string" }, "street_address_2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string", "description": "Two-letter state code." }, "zip_code": { "type": "string", "pattern": "^\\d{5}$" }, "fips_code": { "type": "string", "description": "5-digit FIPS county code." } } }, "MailingAddress": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "properties": { "different_from_home_address": { "type": "boolean", "default": false }, "billing_use_only": { "type": "boolean", "default": false } } } ] }, "HRA": { "type": "object", "description": "Health Reimbursement Arrangement details. Applies to the primary applicant, the employee receiving the HRA offer. If the ICHRA is affordable, all household members are ineligible for premium tax credits.", "additionalProperties": true, "properties": { "offered_hra": { "type": [ "boolean", "null" ], "description": "`true`: applicant is offered an HRA. `false`: applicant is not offered an HRA. `null`: unknown." }, "type": { "type": "string", "enum": [ "ichra", "qsehra" ] }, "amount": { "type": "number", "format": "float", "description": "Monthly contribution in USD." }, "contribution_covers": { "type": "string", "enum": [ "premium", "premium_oop" ], "description": "`premium`: premiums only. `premium_oop`: premiums and out-of-pocket costs." }, "used_for_spousal_or_family_premiums": { "type": "string", "enum": [ "true", "false", "unknown" ], "description": "Whether the HRA is used for spousal or family premiums. Relevant for QSEHRA 834 indicators." }, "start": { "type": "string", "format": "date" }, "employer": { "$ref": "#/components/schemas/Employer" }, "premium_payer": { "type": "string" }, "household_size": { "type": "integer" }, "annual_household_income": { "type": "number", "format": "float" }, "annual_household_income_determination": { "type": "string" } } }, "Employer": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string" }, "external_id": { "type": "string", "description": "Your identifier for this employer group." }, "phone": { "type": "string" }, "fein": { "type": "string", "description": "9-digit Federal Employer Identification Number." }, "address": { "$ref": "#/components/schemas/Address" } } }, "SpecialEnrollmentPeriod": { "type": "object", "additionalProperties": true, "properties": { "event_type": { "type": "string", "enum": [ "birth", "adoption", "death", "divorce", "marriage", "domestic_partnership", "child_support", "loss_of_mec", "loss_of_dependent", "dependent_lost_coverage", "loss_of_pregnancy_coverage", "end_of_non_calendar_year_policy", "change_in_household_status", "lost_aptc", "relocation", "nj_county_change", "offered_ichra", "offered_qsehra", "mandated_covered_dependent", "released_from_incarceration", "returning_active_duty", "provider_not_participating_in_prior_plan", "issuer_violated_contract", "misinformed", "domestic_abuse", "family_care_app_ineligible", "pregnancy", "other" ], "description": "Standardized qualifying event type. HealthSherpa maps these to carrier-specific values automatically. `pregnancy` is accepted in CO, VA, NJ, and MD. For ICHRA enrollments, `offered_ichra` is the most common reason." }, "event_date": { "type": "string", "format": "date" } } }, "Attestations": { "type": "object", "additionalProperties": true, "properties": { "agrees_issuer_attestations": { "type": "boolean" }, "broker_signature_attestation": { "type": "boolean" }, "electronic_signature_consent": { "type": "boolean" }, "disclosure_statement_accepted": { "type": "boolean" }, "coverage_replacement_attestation_accepted": { "type": "boolean" }, "pediatric_dental": { "type": "string", "enum": [ "purchased_separately", "not_applicable" ], "description": "Pediatric dental attestation. `purchased_separately`: pediatric dental purchased via stand-alone dental plan. `not_applicable`: no children under 19 on the application." }, "agent_submitted_application": { "type": "boolean" }, "agent_provided_consumer_marketing_materials": { "type": "boolean" }, "agent_advised_consumer_of_product_features": { "type": "boolean" }, "agent_retained_signed_application_copy": { "type": "boolean" }, "consumer_working_with_agent": { "type": "boolean" }, "spouse_or_dependent_authorization": { "type": "boolean", "description": "Authorization for dependents/spouse to be included on the application." } } }, "Signatures": { "type": "object", "additionalProperties": true, "properties": { "signature_date": { "type": "string", "format": "date", "description": "Date the application was signed. Required for submission. This is separate from `applicants.primary.signature`, the typed name." }, "pediatric_dental_signature": { "type": "string" }, "pediatric_dental_signature_date": { "type": [ "string", "null" ], "format": "date" }, "translator_signature_date": { "type": [ "string", "null" ], "format": "date" }, "state_supplement_primary_signature": { "type": "string", "description": "State-required supplemental form signature for the primary applicant. Required for CO, UT, NJ." }, "state_supplement_spouse_signature": { "type": "string", "description": "State-required supplemental form signature for spouse. Required for UT." }, "state_supplement_disclosures_signature": { "type": "string", "description": "State-required supplemental form disclosures signature for the primary applicant. Required for CO." } } }, "CommunicationPreferences": { "type": "object", "additionalProperties": true, "properties": { "application_notification_email": { "type": "boolean" }, "application_notification_call": { "type": "boolean" }, "application_notification_text": { "type": "boolean" }, "email_contact_consent": { "type": "boolean" }, "marketing_contact_consent": { "type": "boolean" }, "decline_marketing_contact": { "type": "boolean" }, "preferred_communication_method": { "type": "string", "enum": [ "email", "phone", "mail" ] }, "agrees_hsa_contact_opt_in": { "type": "boolean" }, "communication_preference_affirmed": { "type": "boolean", "description": "Whether the applicant has affirmed their communication preferences." } } }, "Analytics": { "type": "object", "description": "Optional tracking and attribution parameters.", "additionalProperties": true, "properties": { "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_term": { "type": "string" }, "utm_content": { "type": "string" } } }, "EnrollmentResponse": { "allOf": [ { "$ref": "#/components/schemas/ApplicationResponse" } ], "description": "Successful direct enrollment application response. Successful responses can contain `errors[]` as submission-readiness data; error responses are documented separately under the `EnrollmentError` response." }, "ApplicationResponse": { "type": "object", "additionalProperties": true, "properties": { "application_id": { "type": "string" }, "external_id": { "type": "string" }, "tpa_slug": { "type": "string" }, "policy_status": { "type": "string", "enum": [ "draft", "pending_effectuation", "effectuated", "submission_failed", "cancelled", "terminated" ], "description": "`draft` when the application has not yet been submitted. Transitions to `pending_effectuation` on successful submission. `submission_failed` means asynchronous carrier submission failed after submit returned." }, "document_status": { "type": [ "string", "null" ], "enum": [ "none_needed", "required", "uploaded", "verified", "denied", null ], "description": "SEP document verification status. `required` means documentation must be uploaded; `uploaded` means sent to carrier pending verification; `verified` means accepted; `denied` means carrier denied the documentation." }, "sep_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "desired_effective_date": { "type": "string", "format": "date" }, "plan_hios_id": { "type": "string" }, "plan_year": { "type": "integer" }, "issuer_hios_id": { "type": "string" }, "payment_instructions": { "$ref": "#/components/schemas/PaymentInstructions" }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/PolicyPaymentStatus" }, { "type": "null" } ], "description": "Carrier-reported payment status. Only present after submission; redirect carriers may not report it immediately." }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyDetail" } }, "application": { "type": "object", "additionalProperties": true, "description": "Echo of the application data as stored." }, "supports_changes": { "type": "boolean", "description": "Whether the carrier supports post-enrollment changes for this application. Only present on submitted applications." }, "can_change_plan": { "type": "boolean", "description": "Whether a plan change is currently allowed. Only present on submitted applications." }, "can_report_change": { "type": "boolean", "description": "Whether demographic changes can be reported. Only present on submitted applications." }, "errors": { "type": "array", "description": "Submission-readiness errors. Present on every successful POST, PUT, and GET response. Empty means the application is ready to submit. Each entry has `code`, `message`, and optional `field`.", "items": { "$ref": "#/components/schemas/SubmissionReadinessError" } }, "next_actions": { "type": "array", "description": "State-aware actions the partner can currently take. HealthSherpa ONE generates `href` and `method` from `rel` so links point at public `/v1/enrollments` routes. POST and PUT actions still require the request bodies documented for those endpoints.", "items": { "$ref": "#/components/schemas/NextAction" } }, "events": { "type": "array", "description": "Audit timeline of the application lifecycle when available, ordered newest-first.", "items": { "$ref": "#/components/schemas/ApplicationEvent" } } } }, "PaymentInstructions": { "type": "object", "description": "Carrier-specific payment guidance.", "additionalProperties": true, "properties": { "payment_required_with_submission": { "type": "boolean", "description": "`true` when payment must be set before submission. Currently applies to Cigna and Elevance in-flow." }, "payment_redirect_supported": { "type": "boolean", "description": "`true` when the carrier supports browser-based payment redirect." }, "pay_by_phone_supported": { "type": "boolean" }, "payment_phone_number": { "type": [ "string", "null" ] } } }, "PolicyPaymentStatus": { "type": "object", "description": "Carrier-reported payment information. Fields are nullable because availability depends on carrier reporting.", "additionalProperties": true, "properties": { "payment_status": { "type": [ "string", "null" ] }, "payment_status_updated_date": { "type": [ "string", "null" ], "format": "date" }, "grace_period_start_date": { "type": [ "string", "null" ], "format": "date" }, "paid_through_date": { "type": [ "string", "null" ], "format": "date" }, "past_due_member_responsibility_balance_due": { "type": [ "string", "null" ] }, "current_member_responsibility_balance_due": { "type": [ "string", "null" ] }, "autopay_indicator": { "type": [ "boolean", "null" ] } } }, "PolicyDetail": { "type": "object", "additionalProperties": true, "properties": { "policy_id": { "type": "string" }, "effective_date": { "type": "string", "format": "date" }, "expiration_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "pending_effectuation", "effectuated", "cancelled", "terminated" ] }, "plan_hios_id": { "type": "string" }, "gross_premium": { "type": "number", "format": "float" }, "members": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "member_id": { "type": "string" }, "effective_date": { "type": "string", "format": "date" }, "removed_date": { "type": [ "string", "null" ], "format": "date" } } } }, "agent_of_record": { "type": "object", "additionalProperties": true, "properties": { "npn": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "state_license_number": { "type": "string" }, "email": { "type": "string" } } }, "payment": { "$ref": "#/components/schemas/PolicyPaymentStatus" } } }, "SubmissionReadinessError": { "type": "object", "description": "Submission-readiness error entry. Appears in the `errors[]` array of a successful enrollment response to indicate what must be completed before the application can be submitted.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code. Switch on this value instead of parsing `message`.", "enum": [ "unauthorized", "token_expired", "forbidden", "not_found", "plan_not_found", "plan_not_available", "missing_required_field", "invalid_field_value", "invalid_field_format", "internal_error", "rate_limit_exceeded", "payload_too_large", "duplicate_external_id", "latest_submission_failed", "supporting_documentation_required", "ineligible_for_enrollment" ] }, "field": { "type": "string", "description": "Dot-path to the offending field when the error is tied to a request field." }, "message": { "type": "string", "description": "Human-readable description of the error. May change over time." } } }, "NextAction": { "type": "object", "description": "State-aware action entry returned on successful enrollment application responses.", "required": [ "rel", "href", "method" ], "additionalProperties": true, "properties": { "rel": { "type": "string", "enum": [ "self", "update", "validate", "submit", "cancel", "terminate", "payment_redirect", "upload_supporting_documentation", "change_plan" ], "description": "Relation type identifying the action." }, "href": { "type": "string", "description": "Relative HealthSherpa ONE URL for the action." }, "method": { "type": "string", "enum": [ "GET", "PUT", "POST" ], "description": "HTTP method to use." }, "required": { "type": "boolean", "description": "When true, this action must be completed before submission. Used for prerequisites like supporting documentation or payment." } } }, "EnrollmentErrorDetail": { "type": "object", "description": "Error entry returned in a direct enrollment failure body (`errors[]`). `code` is intentionally not a closed enum; the values below are the known set and may grow over time, so switch on `code` rather than parsing `message`. `field` is present for field-level validation errors.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code. Known codes: `invalid_request` (400 request/JSON validation, server-owned or `agent_of_record` fields, unsupported `context.exchange`), `idempotency_key_required` (400 missing `Idempotency-Key`), `idempotency_key_invalid` (400 malformed `Idempotency-Key`), `idempotency_in_progress` (409 concurrent retry), `idempotency_mismatch` (422 same key, different body), `unauthorized` (401), `forbidden` (403 not authorized), `rate_limited` (429), `service_unavailable` (503), `internal_error` (500), `token_expired` (401), `not_found` (404), `plan_not_found`, `plan_not_available`, `missing_required_field`, `invalid_field_value`, `invalid_field_format`, `rate_limit_exceeded` (429), `payload_too_large` (413), `duplicate_external_id` (409), `latest_submission_failed`, `supporting_documentation_required`, `ineligible_for_enrollment`." }, "field": { "type": "string", "description": "Dot-path to the offending request field (e.g. `context.exchange`, `_agent_id`, `plan_hios_id`). Present only for field-level errors; omitted for auth, idempotency, and service-level errors." }, "message": { "type": "string", "description": "Human-readable description of the error. May change over time." } } }, "EnrollmentErrorsResponse": { "type": "object", "description": "Error body used by the direct enrollment endpoints for service failures. Each error includes a machine-readable `code`, a human-readable `message`, and may include `field` when the error is tied to a request path.", "additionalProperties": true, "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/EnrollmentErrorDetail" }, "minItems": 1 } } }, "ApplicationEvent": { "type": "object", "required": [ "type", "occurred_at" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "submitted", "changed", "document_status_changed", "cancelled", "submission_failed", "policy_status_updated" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "target": { "type": "string", "enum": [ "application", "applicant" ], "description": "For `changed` events: whether the change was on the application or an applicant record." }, "member_id": { "type": "string", "description": "For applicant change events: member id of the affected applicant." }, "changes": { "type": "array", "description": "Field-level changes. Sensitive fields such as SSN and ITIN are redacted.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] } } } }, "response_code": { "type": "string" }, "carrier_id": { "type": "string" }, "old_status": { "type": "string" }, "new_status": { "type": "string" }, "policy_id": { "type": "string" }, "effective_date": { "type": "string", "format": "date" }, "message": { "type": "string" } } }, "CountySummary": { "type": "object", "additionalProperties": true, "required": [ "fips_code", "name", "state" ], "properties": { "fips_code": { "type": "string", "description": "Five-digit county FIPS code. The first two digits identify the county's state." }, "name": { "type": "string" }, "state": { "type": "string", "description": "Two-letter state code for this county, derived from the FIPS code. Border ZIP responses can include counties from more than one state." } } }, "CountiesResponse": { "type": "object", "additionalProperties": true, "required": [ "counties" ], "properties": { "counties": { "type": "array", "items": { "$ref": "#/components/schemas/CountySummary" } } } }, "IssuerSummary": { "type": "object", "additionalProperties": true, "required": [ "name", "hios_issuer_id" ], "properties": { "name": { "type": "string", "description": "Issuer display name." }, "hios_issuer_id": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Five-digit HIOS issuer ID." } } }, "IssuersResponse": { "type": "object", "additionalProperties": true, "required": [ "issuers" ], "properties": { "issuers": { "type": "array", "description": "Issuers active in the requested state, sorted by `name` (case-insensitive) and then by `hios_issuer_id` as a stable tiebreaker. One entry per HIOS issuer.", "items": { "$ref": "#/components/schemas/IssuerSummary" } } } }, "ProviderEntity": { "type": "object", "additionalProperties": true, "required": [ "npi" ], "properties": { "first_name": { "type": [ "string", "null" ], "description": "Individual provider's first name. Null for organizations." }, "last_name": { "type": [ "string", "null" ], "description": "Individual provider's last name. Null for organizations." }, "organization_name": { "type": [ "string", "null" ], "description": "Organization marketing name. Null for individuals." }, "display_name": { "type": [ "string", "null" ], "description": "Human-friendly label: organization name for facilities, or \"First Last, Credential\" for individuals." }, "credential": { "type": [ "string", "null" ], "description": "Professional credential (e.g. MD, DO, NP)." }, "entity_type": { "type": [ "string", "null" ], "description": "Provider entity type, typically `individual` or `organization`." }, "npi": { "type": "string", "pattern": "^[0-9]{10}$", "description": "Ten-digit National Provider Identifier. Use this value (no suffix) when referencing the provider in enrollment requests." }, "specialty": { "type": [ "string", "null" ], "description": "Primary taxonomy classification (e.g. Family Medicine)." }, "specialization": { "type": [ "string", "null" ], "description": "Primary taxonomy specialization (e.g. General Practice)." }, "address_line_1": { "type": [ "string", "null" ], "description": "First line of the provider's street address (number and street)." }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ], "description": "Two-letter state code." }, "zip_code": { "type": [ "string", "null" ], "description": "The provider's address ZIP code (not the search ZIP)." } } }, "ProvidersResponse": { "type": "object", "additionalProperties": true, "required": [ "providers", "meta" ], "properties": { "providers": { "type": "array", "description": "Provider results for the current page. Empty when there are no matches.", "items": { "$ref": "#/components/schemas/ProviderEntity" } }, "meta": { "$ref": "#/components/schemas/ProvidersResponseMeta" } } }, "ProvidersResponseMeta": { "type": "object", "additionalProperties": true, "required": [ "page_number", "page_size", "result_count" ], "properties": { "page_number": { "type": "integer", "description": "Current page number." }, "page_size": { "type": "integer", "description": "Results per page (at most 50)." }, "result_count": { "type": "integer", "description": "Total number of matches across all pages." } } }, "QuoteRequest": { "type": "object", "additionalProperties": true, "required": [ "context", "location", "household" ], "description": "Canonical quote request for new integrations. Legacy `include` input is accepted for backward compatibility but ignored.", "properties": { "context": { "$ref": "#/components/schemas/QuoteContext" }, "location": { "$ref": "#/components/schemas/LocationInput" }, "household": { "$ref": "#/components/schemas/HouseholdQuoteInput" }, "filters": { "$ref": "#/components/schemas/QuoteFilters" }, "sort": { "$ref": "#/components/schemas/SortInput" }, "page": { "$ref": "#/components/schemas/PageInput" }, "include": { "deprecated": true, "description": "Deprecated and ignored. Accepted for backward compatibility." } } }, "QuoteFilters": { "type": "object", "additionalProperties": true, "properties": { "issuer_ids": { "type": "array", "items": { "type": "string" } }, "premium_min": { "type": "number", "minimum": 0 }, "premium_max": { "type": "number", "minimum": 0 }, "effective_date": { "type": "string", "format": "date" }, "network_types": { "type": "array", "items": { "type": "string" } }, "medical": { "$ref": "#/components/schemas/MedicalFilters" } } }, "MedicalFilters": { "type": "object", "additionalProperties": true, "properties": { "metal_levels": { "type": "array", "items": { "type": "string", "enum": [ "bronze", "expanded_bronze", "silver", "gold", "platinum", "catastrophic" ] } }, "plan_types": { "type": "array", "items": { "type": "string", "enum": [ "hmo", "ppo", "epo", "pos", "indemnity" ] } }, "hsa_eligible": { "type": "boolean" }, "standardized_only": { "type": "boolean" } } }, "QuoteContext": { "type": "object", "additionalProperties": true, "required": [ "product", "exchange", "coverage_family", "coverage_type" ], "properties": { "product": { "type": "string", "enum": [ "aca", "ichra" ] }, "exchange": { "type": "string", "enum": [ "on_exchange", "off_exchange" ] }, "coverage_family": { "type": "string", "enum": [ "medical", "ancillary" ] }, "coverage_type": { "type": "string", "enum": [ "medical", "dental", "vision", "supplemental_other" ] }, "plan_year": { "type": "integer", "minimum": 2020 } } }, "LocationInput": { "type": "object", "additionalProperties": true, "required": [ "zip_code", "fips_code" ], "properties": { "zip_code": { "type": "string", "pattern": "^[0-9]{5}$" }, "fips_code": { "type": "string", "pattern": "^[0-9]{5}$" }, "state": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Quoteable state code for one of the 50 states or DC." } } }, "HouseholdQuoteInput": { "type": "object", "additionalProperties": true, "required": [ "applicants", "household_size" ], "properties": { "applicants": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ApplicantInput" } }, "annual_income": { "type": "number", "minimum": 0 }, "household_size": { "type": "integer", "minimum": 1 }, "effective_date": { "type": "string", "format": "date" } } }, "ApplicantInput": { "type": "object", "additionalProperties": true, "required": [ "member_id", "age", "relationship", "uses_tobacco" ], "properties": { "member_id": { "type": "string", "minLength": 1, "description": "Caller-supplied applicant identifier. Use a stable value from your system, such as `applicant-1`; this is not the applicant relationship. Send `relationship` separately as `primary`, `spouse`, or `dependent`." }, "age": { "type": "integer", "minimum": 0 }, "date_of_birth": { "type": "string", "format": "date" }, "relationship": { "type": "string", "enum": [ "primary", "spouse", "dependent" ] }, "uses_tobacco": { "type": "boolean" }, "gender": { "type": "string", "enum": [ "female", "male", "other", "unknown" ], "description": "Optional applicant gender for quote flows that use gender in marketplace screening." }, "pregnant": { "type": "boolean" }, "blind_or_disabled": { "type": "boolean" }, "native_american": { "type": "boolean" } } }, "SortInput": { "type": "object", "additionalProperties": true, "properties": { "field": { "type": "string" }, "direction": { "type": "string", "enum": [ "asc", "desc" ] } } }, "PageInput": { "type": "object", "additionalProperties": true, "properties": { "number": { "type": "integer", "minimum": 1, "default": 1 }, "size": { "type": "integer", "minimum": 1, "maximum": 500, "default": 20 } } }, "QuoteResponse": { "type": "object", "additionalProperties": true, "required": [ "plans", "meta" ], "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PlanQuoteResult" } }, "meta": { "$ref": "#/components/schemas/QuoteResponseMeta" } } }, "PlanQuoteResult": { "type": "object", "additionalProperties": true, "required": [ "plan_id", "coverage_family", "coverage_type", "name", "api_enrollable", "context", "issuer", "pricing", "documents", "details", "release" ], "properties": { "plan_id": { "type": "string" }, "variant_id": { "type": "string" }, "external_plan_id": { "type": "string" }, "coverage_family": { "type": "string" }, "coverage_type": { "type": "string" }, "name": { "type": "string" }, "display_name": { "type": "string" }, "api_enrollable": { "type": "boolean", "description": "Whether this quoted plan passes the known plan, carrier, and state pre-create gates for direct off-exchange API enrollment at quote time. `true` means the plan can be used with the direct off-exchange enrollment API. `false` means use quote/display only or another enrollment path. This is not consumer ACA eligibility and does not guarantee successful submission after applicant and carrier validation." }, "context": { "type": "object", "additionalProperties": true, "required": [ "product", "exchange", "coverage_family", "coverage_type" ], "properties": { "product": { "type": "string", "enum": [ "aca", "ichra" ] }, "exchange": { "type": "string", "enum": [ "on_exchange", "off_exchange" ] }, "coverage_family": { "type": "string", "enum": [ "medical", "ancillary" ] }, "coverage_type": { "type": "string", "enum": [ "medical", "dental", "vision", "supplemental_other" ] }, "plan_year": { "type": "integer", "minimum": 2020 } } }, "issuer": { "type": "object", "additionalProperties": true, "required": [ "issuer_id", "name" ], "properties": { "issuer_id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string", "nullable": true, "pattern": "^[A-Z]{2}$", "description": "Two-letter US state code where the issuer is licensed." }, "payment_phone": { "type": "string", "nullable": true, "description": "Phone number for member premium-payment inquiries." }, "customer_service_phone": { "type": "string", "nullable": true, "description": "Phone number for general customer-service inquiries." } } }, "network": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "network_id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "nullable": true }, "network_url": { "type": "string", "format": "uri", "nullable": true } } }, "pricing": { "type": "object", "additionalProperties": true, "required": [ "gross_premium", "currency" ], "properties": { "gross_premium": { "type": "number" }, "ehb_premium": { "type": "number" }, "max_aptc": { "type": "number" }, "subsidy_applied": { "type": "number" }, "net_premium": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "billing_period": { "type": "string", "enum": [ "monthly" ] } } }, "documents": { "type": "object", "additionalProperties": true, "description": "Canonical document slots. Carrier-specific source URLs are mapped into these stable fields.", "properties": { "sbc_url": { "type": "string", "format": "uri", "nullable": true, "description": "Summary of Benefits and Coverage document URL." }, "formulary_url": { "type": "string", "format": "uri", "nullable": true }, "brochure_url": { "type": "string", "format": "uri", "nullable": true }, "network_url": { "type": "string", "format": "uri", "nullable": true }, "payment_url": { "type": "string", "format": "uri", "nullable": true, "description": "Issuer-hosted page for making a premium payment." } } }, "availability": { "type": "object", "additionalProperties": true, "description": "Resolved geographic availability lineage produced after county-first location resolution.", "properties": { "state": { "type": "string", "pattern": "^[A-Z]{2}$" }, "service_area_id": { "type": "string", "nullable": true }, "rating_area": { "type": "string", "nullable": true } } }, "details": { "type": "object", "additionalProperties": true, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "medical", "dental", "vision", "supplemental_other" ] }, "metal_level": { "type": "string", "description": "Present for medical quote results.", "enum": [ "bronze", "expanded_bronze", "silver", "gold", "platinum", "catastrophic" ] }, "plan_type": { "type": "string", "description": "Present for medical quote results.", "enum": [ "hmo", "ppo", "epo", "pos", "indemnity" ] }, "hsa_eligible": { "type": "boolean", "nullable": true, "description": "Present for medical quote results." }, "is_standardized": { "type": "boolean", "nullable": true, "description": "Whether the plan follows a CMS- or state-defined standardized design. Present for medical quote results." }, "adult_dental": { "type": "boolean", "nullable": true, "description": "Whether the medical plan embeds adult dental coverage. Present for medical quote results." }, "child_dental": { "type": "boolean", "nullable": true, "description": "Whether the medical plan embeds pediatric (child) dental coverage. Present for medical quote results." }, "deductible_individual": { "type": "number", "nullable": true, "description": "Individual annual deductible (USD). Present for medical quote results." }, "deductible_family": { "type": "number", "nullable": true, "description": "Family annual deductible (USD). Present for medical quote results." }, "moop_individual": { "type": "number", "nullable": true, "description": "Individual maximum out-of-pocket (USD). Present for medical quote results." }, "moop_family": { "type": "number", "nullable": true, "description": "Family maximum out-of-pocket (USD). Present for medical quote results." }, "csr_level": { "type": "string", "nullable": true, "enum": [ "off_exchange", "standard", "csr_zero_cost", "csr_limited", "csr73", "csr87", "csr94", "csr77" ], "description": "CMS CSR variation derived from the 2-digit HIOS variant suffix. Source: PlanAttributes PUF CSRVariationType." }, "primary_care_summary": { "type": "string", "nullable": true, "description": "Cost-share summary for a primary-care visit (e.g. \"$25 Copay\")." }, "specialist_summary": { "type": "string", "nullable": true, "description": "Cost-share summary for a specialist visit." }, "urgent_care_summary": { "type": "string", "nullable": true, "description": "Cost-share summary for an urgent-care visit." }, "generic_rx_summary": { "type": "string", "nullable": true, "description": "Cost-share summary for generic prescription drugs." } } }, "release": { "type": "object", "additionalProperties": true, "required": [ "release_id" ], "properties": { "release_id": { "type": "string" }, "plan_year": { "type": "integer" } } } } }, "QuoteResponseMeta": { "type": "object", "additionalProperties": true, "required": [ "page_number", "page_size", "result_count", "warnings" ], "properties": { "page_number": { "type": "integer" }, "page_size": { "type": "integer" }, "result_count": { "type": "integer" }, "warnings": { "type": "array", "description": "Non-fatal advisories for the request. Includes an include deprecation warning when legacy `include` is supplied.", "items": { "type": "string" } } } }, "EnrollmentSessionRequest": { "type": "object", "additionalProperties": false, "required": [ "context" ], "description": "POST /v1/enrollment-sessions request body. Unsupported fields anywhere in the body are rejected with `400 invalid_request`. In `self_service`, supply at least one of `location.state` or top-level `plan_id`. In `agent_assisted`, `location.state` is required and `plan_id` is not accepted.", "properties": { "external_id": { "type": "string", "description": "Partner-supplied identifier echoed in the response and used for CRM correlation. Strongly recommended; must not contain PII." }, "plan_id": { "type": "string", "description": "Plan ID (HIOS ID). Available only for the `self_service` flow, where it identifies the plan for the generated apply link. Invalid for `agent_assisted` — requests carrying `plan_id` with `context.flow` set to `agent_assisted` are rejected with `400 invalid_request`." }, "notes": { "type": "string", "description": "Free-form note for the assisting agent. Used only in the agent-assisted enrollment flow; ignored on self-service deep links. Capped at 500 characters; longer values are rejected with `400 invalid_request`.", "maxLength": 500 }, "providers": { "type": "array", "description": "Provider identifiers (NPI strings) the household cares about. Used by the agent-assisted enrollment flow and added to the self-service `shopping_url` as a network filter (shop only; not added to `client_apply_url`).", "items": { "type": "string", "description": "Ten-digit National Provider Identifier (NPI).", "pattern": "^[0-9]{10}$" } }, "context": { "$ref": "#/components/schemas/EnrollmentSessionContext" }, "client": { "$ref": "#/components/schemas/EnrollmentSessionClient" }, "location": { "$ref": "#/components/schemas/EnrollmentSessionLocation" }, "household": { "$ref": "#/components/schemas/EnrollmentSessionHousehold" }, "enrollment": { "$ref": "#/components/schemas/EnrollmentSessionEnrollment" }, "campaign": { "$ref": "#/components/schemas/EnrollmentSessionCampaign" } } }, "EnrollmentSessionContext": { "type": "object", "additionalProperties": false, "required": [ "product", "exchange", "coverage_family", "coverage_type", "plan_year", "flow", "locale" ], "properties": { "product": { "type": "string", "enum": [ "aca" ] }, "exchange": { "type": "string", "enum": [ "on_exchange" ] }, "coverage_family": { "type": "string", "enum": [ "medical" ] }, "coverage_type": { "type": "string", "enum": [ "medical" ] }, "plan_year": { "type": "integer", "minimum": 2020, "maximum": 2099 }, "flow": { "type": "string", "enum": [ "agent_assisted", "self_service" ], "description": "Mapped to the deep link's `user_type` (`agent_assisted` -> `agent`, `self_service` -> `consumer`)." }, "locale": { "type": "string", "enum": [ "en-US", "es-MX" ], "description": "`es-MX` enables the Spanish flow via the deep link's `ljs` parameter." } } }, "EnrollmentSessionClient": { "type": "object", "additionalProperties": false, "deprecated": true, "description": "DEPRECATED legacy contact block. Every property here has a 1:1 replacement on `household.applicants[]` and is preferred when both are supplied: `first_name` → `household.applicants[primary].first_name`, `last_name` → `household.applicants[primary].last_name`, `email` → `household.applicants[primary].email`, `phone_number` → `household.applicants[primary].phone_number`. Each field that is still supplied here surfaces a `deprecated_field` entry in the response's `warnings[]` array. The block remains accepted for backwards compatibility but may be removed at any time; migrate to the applicant-level fields.", "properties": { "first_name": { "type": "string", "deprecated": true, "description": "DEPRECATED. Send as `household.applicants[primary].first_name` instead.", "maxLength": 50 }, "last_name": { "type": "string", "deprecated": true, "description": "DEPRECATED. Send as `household.applicants[primary].last_name` instead.", "maxLength": 50 }, "email": { "type": "string", "deprecated": true, "description": "DEPRECATED. Send as `household.applicants[primary].email` instead.", "maxLength": 50 }, "phone_number": { "type": "string", "deprecated": true, "description": "DEPRECATED. Send as `household.applicants[primary].phone_number` instead.", "maxLength": 50 } } }, "EnrollmentSessionLocation": { "type": "object", "additionalProperties": false, "description": "Routing geography plus optional street address. `zip_code`, `fips_code`, and `state` route the request; `address_line_1`, `address_line_2`, and `city` are used by the agent-assisted enrollment flow only and ignored on self-service deep links.", "properties": { "zip_code": { "type": "string", "pattern": "^[0-9]{5}$" }, "fips_code": { "type": "string", "pattern": "^[0-9]{5}$", "description": "Five-digit county FIPS code. Mapped to the deep link's legacy `fip_code` parameter." }, "state": { "type": "string", "description": "Two-letter US state code (50 states plus DC).", "pattern": "^[A-Za-z]{2}$" }, "address_line_1": { "type": "string", "description": "First line of the street address (number and street). Used in the agent-assisted enrollment flow.", "maxLength": 50 }, "address_line_2": { "type": "string", "description": "Optional second line of the street address (apartment, suite). Used in the agent-assisted enrollment flow.", "maxLength": 50 }, "city": { "type": "string", "description": "City of the street address. Used in the agent-assisted enrollment flow; ignored on self-service deep links.", "maxLength": 50 } } }, "EnrollmentSessionHousehold": { "type": "object", "additionalProperties": false, "description": "`household_size` must be at least 1. Applicants can include at most one `primary` and one `spouse`.", "properties": { "annual_income": { "type": "number", "minimum": 0 }, "household_size": { "type": "integer", "minimum": 1 }, "someone_has_employer_coverage": { "type": "boolean" }, "applicants": { "type": "array", "items": { "$ref": "#/components/schemas/EnrollmentSessionApplicant" } } } }, "EnrollmentSessionApplicant": { "type": "object", "additionalProperties": false, "required": [ "relationship" ], "description": "`date_of_birth` and `age` are mutually exclusive on the same applicant, and `date_of_birth` must not be in the future. `sex` accepts `male` and `female`. `first_name` / `last_name` are accepted on every applicant so non-primary members can carry their own identity for the agent-assisted enrollment flow. `email` and `phone_number` are accepted only on the applicant whose `relationship` is `primary` — supplying them on a spouse or dependent is rejected.", "properties": { "relationship": { "type": "string", "enum": [ "primary", "spouse", "dependent" ] }, "first_name": { "type": "string", "description": "Given name. Used by the agent-assisted enrollment flow only; ignored on self-service deep links. Helps prefill household member names in the flow.", "maxLength": 50 }, "last_name": { "type": "string", "description": "Family name. Used by the agent-assisted enrollment flow only; ignored on self-service deep links. Helps prefill household member names in the flow.", "maxLength": 50 }, "email": { "type": "string", "description": "Email for the primary applicant. Used in the agent-assisted enrollment flow and lead lookup. Replaces the deprecated `client.email`; only accepted when `relationship` is `primary`.", "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "maxLength": 50 }, "phone_number": { "type": "string", "description": "Phone number for the primary applicant. Used in the agent-assisted enrollment flow. Replaces the deprecated `client.phone_number`; only accepted when `relationship` is `primary`. Permissive shape — digits with optional spaces, dots, parentheses, hyphens, and a leading `+` (7–50 characters); HealthSherpa normalizes the phone number during the flow.", "pattern": "^[0-9\\s().+\\-]{7,50}$" }, "date_of_birth": { "type": "string", "format": "date" }, "age": { "type": "integer", "minimum": 0, "maximum": 130 }, "sex": { "type": "string", "enum": [ "male", "female" ] }, "uses_tobacco": { "type": "boolean" }, "pregnant": { "type": "boolean" }, "parent_caretaker": { "type": "boolean" }, "rejected_by_medicaid_or_chip": { "type": "boolean" }, "unemployment": { "type": "boolean" }, "has_existing_coverage": { "type": "boolean" }, "ichra": { "$ref": "#/components/schemas/EnrollmentSessionApplicantIchra" }, "prescriptions": { "type": "array", "description": "Medications this applicant takes. Used by the agent-assisted enrollment flow only; ignored on self-service deep links. Nested under the applicant rather than carrying an `applicant_index` linkage field.", "items": { "$ref": "#/components/schemas/EnrollmentSessionApplicantPrescription" } }, "income_sources": { "type": "array", "description": "Income lines attributed to this applicant. Used by the agent-assisted enrollment flow only; ignored on self-service deep links. When any applicant supplies `income_sources`, the per-applicant entries replace the household-level `annual_income` aggregation for the agent-assisted flow; `annual_income` continues to drive the self-service deep link regardless.", "items": { "$ref": "#/components/schemas/EnrollmentSessionApplicantIncomeSource" } } } }, "EnrollmentSessionApplicantPrescription": { "type": "object", "additionalProperties": false, "description": "Medication identification used for Rx-matched plan ranking. At least one of `id` or `rx_norm_identifier` must be supplied; entries with neither are rejected with `400 invalid_request`.", "properties": { "id": { "type": "string", "description": "HealthSherpa medication catalog identifier." }, "duration": { "type": "integer", "description": "Days-of-supply per fill (informational; not used to filter plans).", "minimum": 0 }, "rx_norm_identifier": { "type": "string", "description": "RxNorm CUI for the medication." } } }, "EnrollmentSessionApplicantIncomeSource": { "type": "object", "additionalProperties": false, "required": [ "amount" ], "description": "One income line attributed to this applicant. `amount` is required so the enrollment flow receives usable income information.", "properties": { "employer": { "type": "string", "description": "Employer or payer attributed to this income line.", "maxLength": 50 }, "amount": { "type": "number", "description": "Annual income from this source in dollars.", "minimum": 0 } } }, "EnrollmentSessionApplicantIchra": { "type": "object", "additionalProperties": false, "properties": { "offered": { "type": "boolean" }, "offered_cafeteria": { "type": "boolean" }, "employee_amount": { "type": "number", "minimum": 0 }, "family_amount": { "type": "number", "minimum": 0 } } }, "EnrollmentSessionEnrollment": { "type": "object", "additionalProperties": false, "description": "Accepts `hra`. Other enrollment subobjects (`special_enrollment_period`, `communication_preferences`) are not supported and are rejected with `400 invalid_request`.", "properties": { "hra": { "$ref": "#/components/schemas/EnrollmentSessionEnrollmentHra" } } }, "EnrollmentSessionEnrollmentHra": { "type": "object", "additionalProperties": false, "required": [ "amount" ], "description": "When supplied, `amount` is required and must be greater than or equal to 0. `0` means the consumer declined available HRA funding; a positive value means funding was accepted. `frequency` is required when `amount > 0` and is omitted from the deep link when `amount == 0`.", "properties": { "amount": { "type": "number", "minimum": 0 }, "frequency": { "type": "string", "enum": [ "annually", "monthly", "quarterly", "one_time" ] } } }, "EnrollmentSessionCampaign": { "type": "object", "additionalProperties": false, "description": "Marketing attribution. Only accepted when `context.flow` is `self_service`; sending any field with `flow: \"agent_assisted\"` is rejected with `400 invalid_request`.", "properties": { "cid": { "type": "string" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_term": { "type": "string" }, "utm_content": { "type": "string" }, "display_phone_number": { "type": "string", "pattern": "^\\D?(\\d{3})\\D?\\D?(\\d{3})\\D?(\\d{4})$", "description": "Phone number HealthSherpa renders in the page header. Must be a 10-digit US phone number (any of `8005551234`, `800-555-1234`, `800.555.1234`, `(800) 555-1234` are accepted); `+1`-prefixed and non-10-digit values are rejected with `400 invalid_request`. Forwarded to the deep link's `call` parameter unchanged." } } }, "EnrollmentSessionResponse": { "type": "object", "additionalProperties": true, "required": [ "links" ], "description": "Response envelope. Fields may be null when the request omits optional inputs (for example, `external_id`). Clients must tolerate new top-level keys appearing additively over time. `warnings` is emitted only when the request used a deprecated field; clients should treat its absence as 'no warnings'.", "properties": { "external_id": { "type": "string", "nullable": true, "description": "Echoed from the request when supplied; otherwise null." }, "links": { "$ref": "#/components/schemas/EnrollmentSessionResponseLinks" }, "warnings": { "type": "array", "description": "Non-fatal warnings about the request. Today only the legacy `client.*` contact block emits warnings — one entry per deprecated field that was supplied. The key is omitted entirely when there are no warnings. Clients that want to detect deprecations programmatically should branch on `warnings[].code`.", "items": { "$ref": "#/components/schemas/EnrollmentSessionResponseWarning" } } } }, "EnrollmentSessionResponseWarning": { "type": "object", "additionalProperties": true, "required": [ "code", "field", "message" ], "description": "One non-fatal warning about a single request field. New `code` values may be introduced additively over time; clients should treat unknown codes as 'log and continue'.", "properties": { "code": { "type": "string", "description": "Stable, machine-readable warning category. Currently only `deprecated_field` is emitted (when the request uses a `client.*` contact field that has been replaced by a `household.applicants[]` equivalent)." }, "field": { "type": "string", "description": "Dotted request path of the field this warning is about (for example, `client.email`)." }, "message": { "type": "string", "description": "Human-readable explanation. For deprecation warnings, includes the suggested replacement field path." } } }, "EnrollmentSessionResponseLinks": { "type": "object", "additionalProperties": true, "required": [ "shopping_url", "client_apply_url" ], "properties": { "shopping_url": { "type": "string", "format": "uri", "description": "HealthSherpa public shop URL (https://healthsherpa.com/public/shop?...)." }, "client_apply_url": { "type": "string", "format": "uri", "description": "HealthSherpa public apply URL (https://healthsherpa.com/public/apply?...). Always present for enrollment-session responses." } } }, "ErrorResponse": { "type": "object", "description": "Canonical error envelope returned by HealthSherpa-owned API endpoint, infrastructure filter, and backend service failures. The direct enrollment endpoints return their own service failures using `EnrollmentErrorsResponse` (`errors[]`), but edge-generated failures on those endpoints (API Gateway and WAF, e.g. a missing or invalid API key) still use this `ErrorResponse` envelope. Clients should treat `error.code` as the stable programmatic identifier and surface `error.message` to humans. Recognized codes include:\n- `unauthorized` (401) - backend runtime authentication failure when a request reaches a runtime that performs its own authentication\n- `forbidden` (403) - missing/invalid/unauthorized API key at the API edge, or edge policy deny\n- `invalid_request` (400) - request body or parameter validation failed\n- `not_found` (404) - resource or route not found\n- `payload_too_large` (413) - request body exceeded edge limits\n- `unsupported_media_type` (415) - unsupported Content-Type\n- `rate_limited` (429) - edge rate-limiting\n- `service_unavailable` (503) - the edge is failing to reach the backend, or an upstream catalog/quoting/lookup service is unavailable\n- `bad_gateway` (502) - the edge received an invalid response from the backend\n- `gateway_timeout` (504) - the edge did not receive a timely response from the backend\n- `internal_error` (500) - unexpected server error", "additionalProperties": true, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": true, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable, machine-readable identifier for the error class (see ErrorResponse description for recognized values). Clients should branch on this field rather than on `message` or HTTP status alone." }, "message": { "type": "string", "description": "Human-readable explanation of the error, suitable for logging or surfacing to an end user." }, "details": { "type": "object", "description": "Optional per-field validation details. Keys are dotted/indexed paths (e.g. `household.applicants[0].age`) and values are arrays of full-sentence error messages.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } } } }