---
title: "Get health insurance plan quotes"
method: POST
path: "/api/v1/quotes"
tags: ["Quotes"]
---

# Get health insurance plan quotes

`POST /api/v1/quotes`

Fetch health insurance plans based on location, household details, and filtering criteria

## Request body

- QuotesRequest — Request body for POST /api/v1/quotes endpoint
  - `zip_code` string, required — ZIP code for the location
  - `fip_code` string, required — County code (FIPS) for the location
  - `applicants` object[], required — List of household members applying for coverage
    - `age` integer, required — Age of the applicant
    - `relationship` 'primary' | 'spouse' | 'dependent', required — Relationship to the primary applicant
    - `smoker` boolean, required — Whether the applicant is a smoker
  - `household_income` number — Annual household income. Only required if the client wants subsidy information included in the result.
  - `state` string — State abbreviation
  - `plan_year` integer — Plan year
  - `current_page` integer — Current page number for pagination
  - `per_page` integer — Number of results per page (max 500)
  - `filter` union — Specifies which plan fields to include in the response. Only the requested fields (plus always-included fields: name, year, hios_id, gross_premium) will be returned for each plan. Can be provided as an array or comma-separated string.
    - string[]
    - string
  - `dental_search` boolean — Whether to include dental plans in search
  - `sort` 'premium_asc' | 'premium_desc' | 'deductible_asc' | 'deductible_desc' | 'moop_asc' | 'moop_desc' — Sort order for results
  - `add_attributes` boolean — When true, includes an `attributes` array on each plan with comparative rankings (good/bad/avg) across cost and feature categories.
  - `utilization` 'low' | 'medium' | 'high' — Healthcare usage level for cost modeling. Affects `attributes` rankings. Only meaningful when `add_attributes` is true.
  - `all_benefits` boolean — When true, returns the full SBC benefit list. Default returns a curated subset of commonly compared benefits.
  - `all_details` boolean — When true, includes `cost_sharing_tiers` with per-tier (in-network, in-network tier 2, out-of-network) deductible, MOOP, and coinsurance breakdowns.
  - `off_ex` boolean — Return only off-exchange plans. Otherwise, will only return on-exchange plans.
  - `include_non_enrollable_offex` boolean — If true, includes off-exchange plans the are not enrollable on HealthSherpa.
  - `networks` string[] — Filter by network types
  - `metal_levels` string[] — Filter by metal levels
  - `issuer_hios_ids` string[] — Filter by specific issuer HIOS IDs
  - `providers` string[] — Provider NPIs to include per-plan coverage data for

## Response `200`

Successfully retrieved plan quotes

- object
  - `plans` Plan[]
    - `id` string — Unique plan identifier
    - `hios_id` string, required — Health Insurance Oversight System ID
    - `name` string, required — Plan name
    - `issuer` object — Issuer information
      - `name` string — Insurance company name
      - `hios_id` string — Issuer HIOS ID
      - `state` string — State abbreviation
      - `payment_phone` string, nullable — Payment phone number
      - `customer_service_phone` string, nullable — Customer service phone number
      - `logo_url` string, nullable — URL to the issuer's logo image
      - `eap_disabled` boolean — Whether Employee Assistance Program is disabled
    - `metal_level` string, required — Plan metal level
    - `is_easy_pricing_plan` boolean — Whether this is an easy pricing plan
    - `plan_type` string — Plan type (same as network_type)
    - `network_type` 'HMO' | 'PPO' | 'EPO' | 'POS' | 'Indemnity' — Network type
    - `adult_medical` boolean — Whether plan covers adult medical
    - `child_medical` boolean — Whether plan covers child medical
    - `adult_dental` boolean — Whether plan covers adult dental
    - `child_dental` boolean — Whether plan covers child dental
    - `referral_required_for_specialist` boolean, nullable — Whether referral is required for specialist visits
    - `hsa_eligible` boolean, nullable — Whether plan is HSA eligible
    - `state` string — State abbreviation
    - `dental_only` boolean — Whether this is a dental-only plan
    - `estimated_rate` boolean — Whether the rate is estimated
    - `ichra_only` boolean — Whether this plan is only available to individuals with an ICHRA offer from their employer.
    - `networks` object[] — Network information
      - `id` integer — Network ID
      - `name` string — Network name
      - `year` integer — Plan year
      - `issuer_network_id` string — Issuer's network identifier
    - `year` integer — Plan year
    - `dentist_network_url` string, nullable — URL for dentist network information
    - `csr_code` string — Cost Sharing Reduction code
    - `rating` object — Plan rating information
      - `hios_issuer_id` string — HIOS issuer ID
      - `state` string — State abbreviation
      - `plan_type` string — Plan type
      - `plan_year` integer — Plan year
      - `global_rate` integer — Global rating
      - `s1_rate` integer — S1 rating
      - `s2_rate` integer — S2 rating
      - `s3_rate` integer — S3 rating
    - `cost_sharing` object — Cost sharing details
      - `network_tier` string
      - `csr_type` string
      - `medical_ded_ind` string
      - `medical_ded_fam` string, nullable
      - `drug_ded_ind` string, nullable
      - `drug_ded_fam` string, nullable
      - `medical_moop_ind` string
      - `medical_moop_fam` string
      - `drug_moop_ind` string, nullable
      - `drug_moop_fam` string, nullable
      - `medical_coins` string, nullable
      - `drug_coins` string, nullable
      - `pcp_visit_free_count` integer
      - `pcp_visit_ded_coins_begins_count` integer
    - `csr_level` string — Cost Sharing Reduction level
    - `cost_sharing_pretty` object — Human-readable cost sharing information
      - `csr_type` string
      - `ded_med_ind` string
      - `oop_med_ind` string
      - `oop_med_fam` string
    - `benefits` object — Cost-sharing description per benefit. Curated subset by default; full SBC list when `all_benefits=true`.
    - `benefits_with_tier_2` object — Whether each benefit has separate in-network tier 2 cost-sharing.
    - `benefits_pretty` object — Benefit cost-sharing broken down by deductible phase.
    - `urls` object — Related URLs
      - `network` string, nullable — Network provider directory URL
      - `benefits` string, nullable — Benefits information URL
      - `formulary` string, nullable — Formulary URL
      - `brochure` string, nullable — Plan brochure URL
    - `cost_sharing_tiers` object — Per-tier cost-sharing breakdowns. Populated when `all_details=true`.
      - `inn` object — In-network (primary tier)
      - `inn2` union — In-network tier 2. Returns "No data available" when the plan has no secondary tier.
        - object
        - string
      - `oon` object — Out-of-network
    - `benefits_explanations` object — Carrier-provided supplementary notes for specific benefits. Null when no note is available.
    - `gross_premium` number, float — Gross premium amount before subsidies
    - `ehb_premium` number, float — Essential Health Benefits premium amount
    - `subsidy_applied` number, float — Subsidy amount applied
    - `premium` number, float, required — Final premium amount after subsidies
    - `gross_premium_per_applicant` object — Premium breakdown per applicant
      - `dependents` object[]
      - `non_dependents` object
      - `excluded_dependents` integer
    - `attributes` object[] — Comparative plan rankings across cost and feature categories. Only included when `add_attributes=true`.
      - `text` string — Human-readable ranking label
      - `type` 'good' | 'bad' | 'avg' — Favorable (good), unfavorable (bad), or average (avg) relative to other plans
      - `rank` integer, nullable — Position within the category (1 = best). Null for boolean attributes.
      - `total` integer — Total plans ranked in this category
      - `value` union — Raw value. Numeric for costs, boolean for features, [premium, deductible] array for premium category.
        - number
        - boolean
      - `category` string — Category identifier (e.g., premium, deductible, moop, worst_case, primary_care_cost, specialist_cost, generic_drug).
    - `providers` object — Provider coverage by requested NPI. `covered` is true when in-network, false when not in-network, and null when coverage is unknown.
    - `drugs` object[] — Drug coverage information
    - `prescriptions` object — Prescription information
    - `medicaid_eligible_applicants` object[] — Medicaid eligible applicants
    - `deductible` number, float — Annual deductible amount (legacy field, use cost_sharing for detailed info)
    - `moop` number, float — Maximum out-of-pocket amount (legacy field, use cost_sharing for detailed info)
    - `issuer_name` string — Insurance company name (legacy field, use issuer.name)
  - `meta` Meta
    - `result_count` integer, required — total number of results
    - `zip_code` string — zip code used for the quote. In the response when no results are returned.
    - `fip_code` string — fip code used for the quote. In the response when no results are returned.
    - `message` string — message to the user when no results are returned.

## Other responses

- `401` — Unauthorized - missing or invalid API token
- `422` — Bad Request - Invalid parameters
- `500` — Internal Server Error

---

[API](https://skmtc.net/healthsherpa/apis/health-insurance-quotes-api.md) · [All operations](https://skmtc.net/healthsherpa/apis/health-insurance-quotes-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/healthsherpa/health-insurance-quotes-api/revisions/3cbfff4e5929/schema)