One ACA marketplace plan
GET /v1/marketplace/plans/{plan_id}
GET https://api.healthcare.dev/v1/marketplace/plans/{plan_id}Preview: 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). One marketplace plan as the CMS Exchange public use files list it: issuer, metal level, plan type, service area (counties, partial counties with their ZIP codes), monthly premiums by rating area and age as published (with tobacco and family-tier rates where the plan has them), each cost-sharing variant's deductibles and out-of-pocket maximums (medical, drug or combined; in network, second tier, out of network), its benefits and cost sharing as published (copay and coinsurance per network tier, quantity limits, whether it counts toward the out-of-pocket maximum), and the issuer's links (formulary, brochure, summary of benefits). plan_id is the 14-character plan id (29418TX0140108); a variant id (29418TX0140108-01) finds its plan. rating_area and age narrow the premiums. 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.
Path parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
plan_id | string | yes | Plan id (HIOS standard component id), or a variant id | 29418TX0140108 |
Query parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
rating_area | string | no | Only this rating area: 3 or Rating Area 3 | 1 |
age | integer | null | no | Only the rate for this age (0 to 14 share one rate, as do 64 and over); family-tier rates are kept | 40 |
view | "compact" | "standard" | "full" | no | How much of each record to return (default full). compact: id, name, issuer, state, metal_level, plan_type, cost_sharing, premiums, links (fewest tokens, for agents). standard: every field except variants, replaced_by. 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, product_id, network_id, formulary_id, design_type, new_plan, hsa_eligible, national_network, specialist_referral_required, child_only_offering, service_area, rating_areas, cost_sharing, premiums, variants, links, effective_date, expiration_date, cms_import_date, status, effective_start, effective_end, replaced_by. | id,name,issuer |
Examples
curl
curl "https://api.healthcare.dev/v1/marketplace/plans/29418TX0140108" \
-H "Authorization: Bearer $HDEV_API_KEY"TypeScript
const res = await fetch("https://api.healthcare.dev/v1/marketplace/plans/29418TX0140108", {
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/29418TX0140108", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()Try it
Response
The plan
{
"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",
"product_id": "string",
"network_id": "string",
"formulary_id": "string",
"design_type": "string",
"new_plan": true,
"hsa_eligible": true,
"national_network": true,
"specialist_referral_required": true,
"child_only_offering": "string",
"service_area": {
"id": "string",
"name": "string",
"covers_entire_state": true,
"counties": [
{
"fips": null,
"partial": null,
"zip_codes": null
}
]
},
"rating_areas": [
"string"
],
"cost_sharing": {
"variant_id": "string",
"deductible": 0,
"moop": 0
},
"premiums": [
{
"rating_area": "string",
"effective_date": "2026-10-01",
"expiration_date": "2026-10-01",
"tobacco_rated": true,
"rates": [
null
],
"family": null
}
],
"variants": [
{
"id": "string",
"name": "string",
"csr_variation": "string",
"issuer_actuarial_value": "string",
"medical_drug_deductibles_integrated": true,
"medical_drug_moop_integrated": true,
"deductibles": null,
"moop": null,
"summary_of_benefits_url": "string",
"benefits": [
null
]
}
],
"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",
"cms_import_date": "2026-10-01",
"status": "active",
"effective_start": "2026-10-01",
"effective_end": "2026-10-01",
"replaced_by": [
"string"
]
},
"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/29418TX0140108",
"next": null
}
}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 |
product_id | string | yes | HIOS product id |
network_id | string | null | yes | |
formulary_id | string | null | yes | |
design_type | string | null | yes | Standardized plan design, as published (Design 1) |
new_plan | boolean | yes | New this plan year (CMS: New vs Existing) |
hsa_eligible | boolean | null | yes | |
national_network | boolean | null | yes | Whether the plan has a national network (null: not stated) |
specialist_referral_required | boolean | null | yes | |
child_only_offering | string | null | yes | As published, e.g. Allows Adult and Child-Only |
service_area | MarketplaceServiceArea | 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 |
premiums | MarketplacePremiums[] | yes | Per rating area and rate period |
variants | MarketplacePlanVariant[] | yes | Cost-sharing variants, by id |
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 | |
cms_import_date | string | null (date) | yes | When CMS imported the issuer's data into the file |
status | "active" | "retired" | "replaced" | yes | |
effective_start | string (date) | yes | |
effective_end | string | null (date) | yes | |
replaced_by | string[] | no |
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. |