# One ACA marketplace plan

URL: https://docs.healthcare.dev/reference/marketplace/one-aca-marketplace-plan

```http
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](/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**

```sh
curl "https://api.healthcare.dev/v1/marketplace/plans/29418TX0140108" \
  -H "Authorization: Bearer $HDEV_API_KEY"
```

**TypeScript**

```ts
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**

```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()
```

## Response

The plan

```json
{
  "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](https://www.rfc-editor.org/rfc/rfc9457)). Branch on `type`, not on `title`. See [Errors](/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. |