HealthSherpa Policy Status API

openapi: 3.2.0
info:
  title: HealthSherpa Public Policy Status API
  version: 0.1.0
  termsOfService: https://one.healthsherpa.com/legal/healthsherpa-one-api-terms-of-service.html
  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.


    Most 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`).


    ## Terms and compliance


    - HealthSherpa ONE API Terms of Service

    - Compliance considerations

    - CMS web-broker guidance

    - 45 CFR § 155.220'
  x-rate-limits:
    description: Each API key is assigned one throughput tier. Its rate and burst limits apply to every API route. A shared stage limit also applies across callers.
    defaultTier: low
    monthlyQuotaPeriod: MONTH
    sharedStage:
      rateLimitRps: 20
      burstLimit: 30
    tiers:
      low:
        rateLimitRps: 1
        burstLimit: 2
        monthlyQuota: 100000
      medium:
        rateLimitRps: 5
        burstLimit: 10
        monthlyQuota: 500000
      high:
        rateLimitRps: 10
        burstLimit: 20
        monthlyQuota: 1000000
servers:
- url: https://api.one.healthsherpa.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Policy Status
paths:
  /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'
components:
  schemas:
    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
    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
    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.
    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'
    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:

        - `unauthorized` (401) - backend runtime authentication failure when a request reaches a runtime that performs its own authentication

        - `forbidden` (403) - missing/invalid/unauthorized API key at the API edge, or edge policy deny

        - `invalid_request` (400) - request body or parameter validation failed

        - `not_found` (404) - resource or route not found

        - `payload_too_large` (413) - request body exceeded edge limits

        - `unsupported_media_type` (415) - unsupported Content-Type

        - `rate_limited` (429) - edge rate-limiting

        - `service_unavailable` (503) - the edge is failing to reach the backend, or an upstream catalog/quoting/lookup service is unavailable

        - `bad_gateway` (502) - the edge received an invalid response from the backend

        - `gateway_timeout` (504) - the edge did not receive a timely response from the backend

        - `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
  responses:
    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.
    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.
    InternalError:
      description: An unexpected error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: internal_error
              message: An unexpected error occurred.
    RateLimited:
      description: The per-key throughput tier, monthly quota, or shared stage limit was exceeded. Per-key tier limits apply to every API route. Clients should honor Retry-After when present and retry with exponential backoff and jitter.
      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.
    Forbidden:
      description: The API key is missing, invalid, not authorized for this API, or the request was blocked at the API edge. Edge policy may deny requests from identified anonymous proxies, VPNs, and Tor exits, plus requests matching known bad input or high-confidence SSRF, LFI, RFI, restricted-extension, or cross-site-scripting signatures. Do not retry an unchanged edge-blocked request; contact developer support if a legitimate request is blocked. 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.
    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'
    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`.


        A 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
    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.
    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
    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.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Developer portal API key. Server-side credential: send it only from your backend and never embed it in browser JavaScript, mobile apps, public environment variables, or source control. Requests made with a key count against that key''s throughput tier and monthly quota. Activating a new key in the developer portal disables the previous key.'
externalDocs:
  description: Compliance considerations
  url: https://one.healthsherpa.com/docs/integration-guide/compliance-considerations.html
x-provenance:
  method: harvested
  publisher: HealthSherpa
  source: https://one.healthsherpa.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)