# Plan details

`GET https://api.inplan.io/v1/plans/{plan_id}`

Plan details for a marketplace or Medicare Advantage plan: name, insurer or organization, plan type, the plan years we hold, and whether we hold its provider listings.

Free plan and up · 1 call. Source: https://inplan.io/docs/api/plans

## When to use it

Use it to show which plan a user picked, to validate a plan id before you store it, or to read `available_years`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `plan_id` | path | string | Required | A marketplace plan id or a Medicare Advantage contract-plan-segment id. Example: `29276OH0970001 · H2526-001-000`. |
| `year` | query | integer | Optional | The plan year of the details. Default: the newest year we hold. Example: `2026`. |

## Request

curl:

```bash
curl https://api.inplan.io/v1/plans/29276OH0970001 \
  -H "Authorization: Bearer $INPLAN_KEY"
```

JavaScript:

```javascript
const res = await fetch("https://api.inplan.io/v1/plans/29276OH0970001", {
  headers: { Authorization: `Bearer ${process.env.INPLAN_KEY}` },
});
const body = await res.json();
console.log(body.data.plan_name, body.data.available_years);
```

Python:

```python
import os, requests

res = requests.get(
    "https://api.inplan.io/v1/plans/29276OH0970001",
    headers={"Authorization": f"Bearer {os.environ['INPLAN_KEY']}"},
    timeout=10,
)
body = res.json()
print(body["data"]["plan_name"], body["data"]["available_years"])
```

## Response fields

Every response has the envelope `request_id`, `data_as_of`, `data`, `sources` and `notes`. Fields of `data`:

| Field | Type | Description |
| --- | --- | --- |
| `market` | string | `aca` or `ma`. |
| `plan_id` | string | The normalized plan id. |
| `plan_year` | integer | The plan year of these details: the `year` you sent, else the newest year we hold. |
| `plan_name` | string | The plan name as published. |
| `issuer` | object | Marketplace plans: the insurer. |
| `issuer.id` | string | The 5-digit insurer id. |
| `issuer.name` | string | The insurer name. |
| `state` | string | Marketplace plans: the plan state. |
| `metal_level` | string | Marketplace plans: the metal level. |
| `plan_type` | string | HMO, PPO, EPO, POS and similar. |
| `markets` | string[] | Marketplace plans: the markets the plan is sold in, for example Individual. |
| `network_id` | string | Marketplace plans: the insurer's network id for this plan. |
| `variant_ids` | string[] | Marketplace plans: every variant id of this plan. |
| `plan_details_available` | boolean | `true` when plan name and plan details are included. |
| `listings` | object | Whether we hold provider listings for this plan. |
| `listings.has_listings` | boolean | `true` when we hold provider listings for this plan. |
| `listings.as_of` | date | The date we read its directory. |
| `variant` | string \| null | Marketplace plans: the variant you sent, else `null`. |
| `input_plan_id` | string | The plan id exactly as you sent it. |
| `available_years` | integer[] | Every plan year we hold for this plan. |
| `links` | object | Related endpoints. |
| `links.providers` | string | The path of the provider list for this plan. |
| `links.check` | string | A check path for this plan. Put an NPI in place of `{npi}`. |
| `contract_id` | string | Medicare Advantage plans: the contract id (the part before the first dash). |
| `contract_name` | string | Medicare Advantage plans: the contract name as published. |
| `organization` | string | Medicare Advantage plans: the organization that offers the plan. |
| `parent_organization` | string | Medicare Advantage plans: the parent organization. |
| `category` | string | Medicare Advantage plans: the plan category, for example MA-PD. |
| `snp` | object | Medicare Advantage plans: special needs plan details. |
| `snp.is_snp` | boolean | `true` for a special needs plan. |
| `snp.type` | string | The special needs plan type, as published. |
| `service_area` | object | Medicare Advantage plans: the service area. |
| `service_area.states` | string[] | States in the service area. |
| `service_area.counties` | integer | Number of counties in the service area. |
| `star_rating` | number \| null | Medicare Advantage plans: the overall star rating published for the plan. |
| `monthly_premium` | object | Medicare Advantage plans: the monthly premium range in US dollars. |
| `monthly_premium.min` | integer | Lowest monthly premium. |
| `monthly_premium.max` | integer | Highest monthly premium. |

## Responses

### 200 aca

A marketplace plan.

Response (200 OK · application/json):

```json
{
  "request_id": "req_qekrIghme3OYo8pW",
  "data_as_of": "2026-10-29",
  "data": {
    "market": "aca",
    "plan_id": "29276OH0970001",
    "plan_year": 2026,
    "plan_name": "Anthem Bronze Pathway 10600 ($0 Virtual PCP + $0 Select Drugs)",
    "issuer": {
      "id": "29276",
      "name": "Anthem Blue Cross and Blue Shield"
    },
    "state": "OH",
    "metal_level": "Bronze",
    "plan_type": "HMO",
    "markets": [
      "Individual"
    ],
    "network_id": "OHN004",
    "variant_ids": [
      "29276OH0970001-00",
      "29276OH0970001-01",
      "29276OH0970001-02",
      "29276OH0970001-03"
    ],
    "plan_details_available": true,
    "listings": {
      "has_listings": true,
      "as_of": "2026-07-27"
    },
    "variant": null,
    "input_plan_id": "29276OH0970001",
    "available_years": [
      2026
    ],
    "links": {
      "providers": "/v1/plans/29276OH0970001/providers",
      "check": "/v1/check?plan_id=29276OH0970001&npi={npi}"
    }
  },
  "sources": [
    {
      "type": "insurer_directory",
      "description": "Provider network directories published by health insurers",
      "as_of": "2026-10-29"
    },
    {
      "type": "plan_catalog",
      "description": "Published health plan catalogs",
      "as_of": "2026-10-28"
    }
  ]
}
```

### 200 ma

A Medicare Advantage plan, with service area, star rating and premium range.

Response (200 OK · application/json):

```json
{
  "request_id": "req_QQiaxVHE9rtUs9XV",
  "data_as_of": "2026-10-29",
  "data": {
    "market": "ma",
    "plan_id": "H2526-001-000",
    "plan_year": 2027,
    "plan_name": "DEVOTED CHOICE 001 OH (PPO)",
    "contract_id": "H2526",
    "contract_name": "DEVOTED HEALTH PLAN OF OHIO INC",
    "organization": "Devoted Health",
    "parent_organization": "Devoted Health, Inc.",
    "plan_type": "PPO",
    "category": "MA-PD",
    "snp": {
      "is_snp": false,
      "type": "Not Applicable"
    },
    "service_area": {
      "states": [
        "OH"
      ],
      "counties": 78
    },
    "star_rating": 4.5,
    "monthly_premium": {
      "min": 0,
      "max": 0
    },
    "plan_details_available": true,
    "listings": {
      "has_listings": true,
      "as_of": "2026-10-29"
    },
    "input_plan_id": "H2526-001-000",
    "available_years": [
      2027,
      2026
    ],
    "links": {
      "providers": "/v1/plans/H2526-001-000/providers",
      "check": "/v1/check?plan_id=H2526-001-000&npi={npi}"
    }
  },
  "sources": [
    {
      "type": "plan_directory",
      "description": "Provider network directories published by Medicare Advantage plans",
      "as_of": "2026-10-29"
    },
    {
      "type": "plan_catalog",
      "description": "Published health plan catalogs",
      "as_of": "2026-10-28"
    }
  ]
}
```

### 401

The `Authorization` header is missing or malformed, or the key is unknown or revoked.

Response (401 Unauthorized · application/problem+json):

```json
{
  "type": "unauthorized",
  "title": "Missing API key",
  "status": 401,
  "detail": "Send `Authorization: Bearer ip_live_...`.",
  "instance": "/v1/plans/29276OH0970001",
  "request_id": "req_fyedh_HTRJB21DW8",
  "docs": "https://inplan.io/docs/errors#unauthorized"
}
```

### 404

We hold no plan with this id, or not the `year` you asked for.

Response (404 Not Found · application/problem+json):

```json
{
  "type": "plan_not_found",
  "title": "Plan not found",
  "status": 404,
  "detail": "No plan found for 99999OH0010001.",
  "instance": "/v1/plans/99999OH0010001",
  "request_id": "req_yJz9v1z9Xg6vHNi9",
  "docs": "https://inplan.io/docs/errors#plan_not_found"
}
```

## Errors

Errors use `application/problem+json` (RFC 7807): `type`, `title`, `status`, `detail`, `instance`, `request_id`, `docs`. Other statuses this endpoint can return: `400` (an id in neither format: `invalid_plan_id`), `403`, `429` and `503`. See [Errors](https://inplan.io/docs/errors).

## Rate-limit headers

Every response that passes the key and plan checks carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`, `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset` and `X-Request-Id`. See [Rate limits and quotas](https://inplan.io/docs/rate-limits).