# Plans and plan years

The API takes marketplace plan ids and Medicare Advantage contract-plan-segment ids. Each answer names the plan year it is about.

Source: https://inplan.io/docs/plans-and-plan-years · Updated 2026-10-30

## Plan id formats

| Market | Format | Example |
| --- | --- | --- |
| Marketplace | 5-digit insurer id, 2-letter state, 7 digits (14 characters) | `29276OH0970001` |
| Marketplace variant | The 14 characters plus a 2-digit variant, with or without a dash | `29276OH0970001-01` |
| Medicare Advantage | Contract (H or R and 4 digits), plan number, segment | `H2526-001-000` |

Ids are not case sensitive. A Medicare Advantage id without a segment (`H2526-001`) means segment `000`. Any other format answers `400 invalid_plan_id`.

## Marketplace variants

Insurer directories list providers under the 14-character plan id, so a variant id is checked against its plan. `plan_id` in the answer is the 14-character id, `input_plan_id` echoes what you sent, and `plan.variant` holds the variant.

Response (200 OK · variant id):

```json
{
  "data": {
    "npi": "1184617268",
    "plan_id": "29276OH0970001",
    "input_plan_id": "29276OH0970001-01",
    "market": "aca",
    "plan_years_listed": [
      2026
    ],
    "in_network": true,
    "answer": "listed",
    "explanation": "The insurer's network directory lists this provider for this plan.",
    "evidence": [
      {
        "plan_id": "29276OH0970001",
        "plan_year": 2026,
        "network_tier": "PARTICIPATING",
        "source": {
          "type": "insurer_directory",
          "as_of": "2026-07-27"
        }
      }
    ],
    "plan_year": 2026,
    "plan": {
      "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",
      "variant": "01"
    },
    "source": {
      "type": "insurer_directory",
      "as_of": "2026-07-27"
    },
    "as_of": "2026-07-27"
  }
}
```

## Plan years

A plan can have listings for more than one plan year. Without `year`, a check looks at every year we hold and `plan_year` is the newest year listed. With `year`, the answer covers that year only.

curl:

```bash
curl https://api.inplan.io/v1/check \
  -H "Authorization: Bearer $INPLAN_KEY" \
  -G -d npi=1184617268 -d plan_id=29276OH0970001 -d year=2026
```

JavaScript:

```javascript
const url = new URL("https://api.inplan.io/v1/check");
url.search = new URLSearchParams({ npi: "1184617268", plan_id: "29276OH0970001", year: "2026" });

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.INPLAN_KEY}` },
});
const body = await res.json();
console.log(body.data.plan_year, body.data.answer);
```

Python:

```python
import os, requests

res = requests.get(
    "https://api.inplan.io/v1/check",
    params={"npi": "1184617268", "plan_id": "29276OH0970001", "year": "2026"},
    headers={"Authorization": f"Bearer {os.environ['INPLAN_KEY']}"},
    timeout=10,
)
body = res.json()
print(body["data"]["plan_year"], body["data"]["answer"])
```

`year` must be a 4-digit year from 2025 to 2030. `plan_years_listed` lists every year in which the directory lists the provider. `GET /v1/plans/{plan_id}` returns `available_years` for a plan.

## Plan details

`GET /v1/plans/{plan_id}` returns the name, insurer or organization, plan type and, for marketplace plans, metal level and state. Medicare Advantage plans add the service area, star rating and premium range. `listings.has_listings` tells you whether we hold provider listings for the plan.

Response (200 OK · Medicare Advantage plan):

```json
{
  "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}"
    }
  }
}
```

When we hold listings for a plan but not its details, `plan_details_available` is `false` and the name fields are `null`.

## Prescription drug plans

Ids that start with S are prescription drug plans. They have no provider network, so a check answers `no_provider_network` with `in_network: null`.