ACA marketplace plans
GET /v1/marketplace/plans
GET https://api.healthcare.dev/v1/marketplace/plansPreview: not available yet (503 dataset-unavailable until it is released). Pro plan and up (below Pro: a few preview calls a month, then 403 plan-upgrade-required). Health plans sold on the ACA marketplace in the states on the federal platform (HealthCare.gov), from the CMS Exchange public use files for the plan year: issuer, metal level, plan type, service area, rating areas and the standard variant's deductible and out-of-pocket maximum. Filter by state, county (5-digit FIPS: plans whose service area covers it), metal level, plan type, market, dental or medical, and issuer. Sorted by plan id. Then GET /v1/marketplace/plans/{plan_id} for premiums by age and rating area, every variant's deductibles and out-of-pocket maximums, and benefits. Derived from the CMS Health Insurance Exchange public use files for the plan year, as CMS published them; not CMS data, and it may differ from what HealthCare.gov shows. Covers the states on the federal platform (HealthCare.gov), not states running their own exchange. Premiums are the issuer's monthly base rates by age and rating area before any subsidy. Check the issuer's documents (links) before relying on a detail.
Requires an API key: Authorization: Bearer hdev_live_.... See Authentication.
Query parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
state | string | no | Two-letter state | TX |
county | string | no | County FIPS code (5 digits): plans whose service area covers all or part of it | 48453 |
metal | string | no | Metal level: bronze, expanded_bronze, silver, gold, platinum, catastrophic; dental high or low | silver |
plan_type | string | no | HMO, PPO, EPO, POS or Indemnity | HMO |
market | "individual" | "shop" | no | individual or shop (small group) | individual |
dental | "true" | "false" | no | true: stand-alone dental plans only; false: medical only | true |
issuer | string | no | HIOS issuer id (5 digits) | 29418 |
limit | integer | no | Page size (max 100) | 25 |
cursor | string | no | Opaque cursor from links.next | |
view | "compact" | "standard" | "full" | no | How much of each record to return (default full). compact: id, name, issuer, metal_level, plan_type, cost_sharing (fewest tokens, for agents). standard: every field except links. full: every field. | compact |
fields | string | no | Comma-separated fields to return instead of a view. Valid fields: id, plan_year, name, issuer, state, market, dental_only, metal_level, plan_type, exchange, network_id, service_area, rating_areas, cost_sharing, links, effective_date, expiration_date. | id,name,issuer |
Examples
curl
curl "https://api.healthcare.dev/v1/marketplace/plans?limit=25" \
-H "Authorization: Bearer $HDEV_API_KEY"TypeScript
const res = await fetch("https://api.healthcare.dev/v1/marketplace/plans?limit=25", {
headers: { Authorization: `Bearer ${process.env.HDEV_API_KEY}` },
});
const { data, meta } = await res.json();Python
import os
import requests
res = requests.get("https://api.healthcare.dev/v1/marketplace/plans?limit=25", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()Try it
Response
Plans, by id
{
"data": [
{
"id": "string",
"plan_year": 1,
"name": "string",
"issuer": {
"id": "string",
"name": "string"
},
"state": "string",
"market": "individual",
"dental_only": true,
"metal_level": "string",
"plan_type": "string",
"exchange": "on_and_off",
"network_id": "string",
"service_area": {
"id": "string",
"name": "string",
"covers_entire_state": true,
"county_count": 1
},
"rating_areas": [
"string"
],
"cost_sharing": {
"variant_id": "string",
"deductible": 0,
"moop": 0
},
"links": {
"formulary_url": "string",
"brochure_url": "string",
"summary_of_benefits_url": "string",
"enrollment_payment_url": "string"
},
"effective_date": "2026-10-01",
"expiration_date": "2026-10-01"
}
],
"meta": {
"source": "cms-icd10",
"data_version": "2026.1",
"retrieved_at": "2026-10-24T12:00:00Z",
"license": "Public domain (CMS). Reference data, not medical advice."
},
"links": {
"self": "/v1/marketplace/plans?limit=25",
"next": "/v1/marketplace/plans?limit=25&cursor=eyJrIjoiRTExLjkifQ"
}
}Fields
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | Plan id (HIOS standard component id), e.g. 29418TX0140108 |
plan_year | integer | yes | |
name | string | yes | |
issuer | MarketplaceIssuer | yes | |
state | string | yes | |
market | MarketplaceMarket | yes | individual market, or shop (the Small Business Health Options Program) |
dental_only | boolean | yes | A stand-alone dental plan |
metal_level | string | yes | bronze, expanded_bronze, silver, gold, platinum, catastrophic; dental plans high or low |
plan_type | string | yes | As published: HMO, PPO, EPO, POS, Indemnity |
exchange | "on_and_off" | "on" | "off" | yes | Offered on the exchange, off it, or both |
network_id | string | null | yes | |
service_area | object | yes | |
rating_areas | string[] | yes | Rating areas the plan has premiums for |
cost_sharing | MarketplaceCostSharing | yes | The individual in-network deductible and out-of-pocket maximum of the plan's standard variant (-01 on exchange, else -00): the combined medical and drug amount when the plan integrates them, else the medical one. Every variant's full amounts are in variants |
links | MarketplaceLinks | yes | The issuer's own pages, as listed in the plan attributes file (links only) |
effective_date | string | null (date) | yes | |
expiration_date | string | null (date) | yes |
Errors
Errors are application/problem+json (RFC 9457). Branch on type, not on title. See Errors.
| Status | type | When |
|---|---|---|
| 400 | invalid-request | A parameter or the body failed validation; errors lists each field. |
| 401 | unauthorized | Missing, malformed or revoked API key. |
| 403 | plan-upgrade-required | The plan doesn't include this feature; required_plan names the plan that does. |
| 404 | not-found | No record with that id (retired records are still returned). |
| 429 | rate-limited / quota-exceeded | Too many requests per second (retry after Retry-After), or the monthly quota is used up. |
| 503 | dataset-unavailable / unavailable | The dataset has no published version yet, or the service is degraded. |