Skip to content
Opelyx Docs

Look up plan year-over-year crosswalk

GET
/v1/health/plans/crosswalk

Maps a plan from one year to the next. Shows if the plan ID changed, was discontinued with a replacement, or was discontinued with no replacement. Requires Pro or Enterprise subscription.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
plan_id
required
string
>= 14 characters <= 14 characters /^\d{5}[A-Z]{2}\d{7}$/

14-character HIOS standard_component_id. No variant suffix (e.g., 47163FL0810001 not 47163FL0810001-01).

Example
47163FL0810001
year
required
integer
Allowed values: 2025

Source plan year. Crosswalk maps plans from this year to year+1. Currently only 2025 is available.

Example
2025
state
required
string
>= 2 characters <= 2 characters /^[A-Z]{2}$/

2-letter state code. Only FFM and SBE-FP states (30 states) have crosswalk data.

Example
FL

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Crosswalk result mapping a plan from one year to the next

Year-over-year plan crosswalk result showing how a plan maps from one year to the next

object
_links
required
object
self

A HAL link object (draft-kelly-json-hal-11 §5)

object
href
required

Target URI or URI Template

string format: uri-reference
templated

True when href is an RFC 6570 URI Template

boolean
type

Media type hint for the target resource

string
title

Human-readable link title

string
source_plan
required

The plan being looked up (previous year)

object
plan_id
required

14-character HIOS standard_component_id

string
Example
47163FL0810001
year
required

Plan year

integer
Example
2025
state
required

2-letter state code

string
Example
FL
name

Plan marketing name

string
nullable
Example
Ambetter Essential Care 1 (2025)
issuer_id

5-digit HIOS issuer ID

string
Example
47163
issuer_name

Insurance company name

string
nullable
Example
Ambetter of Sunshine Health
target_plan
required

The mapped plan in the next year. null when crosswalk_reason is ‘plan_discontinued_no_replacement’.

object
plan_id

14-character HIOS standard_component_id

string
Example
47163FL0810003
year

Plan year

integer
Example
2026
state

2-letter state code

string
Example
FL
name

Plan marketing name

string
nullable
Example
Ambetter Essential Care 2
issuer_id

5-digit HIOS issuer ID

string
Example
47163
issuer_name

Insurance company name

string
nullable
Example
Ambetter of Sunshine Health
crosswalk_reason
required

Human-readable crosswalk reason

string
Allowed values: plan_default_crosswalk plan_id_changed plan_discontinued_crosswalked plan_discontinued_no_replacement plan_crosswalked_county_level plan_crosswalked_issuer_change plan_crosswalked_service_area_change plan_crosswalked_multi_factor
reason_code
required

CMS crosswalk reason code: 0 = default crosswalk, 1 = plan ID changed, 2 = discontinued with replacement, 3 = discontinued with no replacement, 6 = county-level crosswalk, 7 = issuer change, 8 = service area change, 10 = multi-factor crosswalk

integer
Allowed values: 0 1 2 3 6 7 8 10
data_source
required

Data origin

string
Example
puf_data
data_freshness
required

Data freshness label

string
Example
{
  "_links": {
    "self": {
      "href": "https://api.opelyx.com/v1/health/plans/crosswalk?plan_id=47163FL0810001&year=2025&state=FL",
      "type": "application/json"
    }
  },
  "source_plan": {
    "plan_id": "47163FL0810001",
    "year": 2025,
    "state": "FL",
    "name": "Ambetter Essential Care 1 (2025)",
    "issuer_id": "47163",
    "issuer_name": "Ambetter of Sunshine Health"
  },
  "target_plan": {
    "plan_id": "47163FL0810003",
    "year": 2026,
    "state": "FL",
    "name": "Ambetter Essential Care 2",
    "issuer_id": "47163",
    "issuer_name": "Ambetter of Sunshine Health"
  },
  "crosswalk_reason": "plan_id_changed",
  "reason_code": 1,
  "data_source": "puf_data",
  "data_freshness": "PY2026 CMS PUF (30 FFM) + state exchange data (21 SBM). All 50 states + DC covered"
}

Headers

Section titled “Headers ”
X-Request-Id
string format: uuid

Unique request identifier for tracing

Link
string

RFC 8288 Web Linking (pagination and resource discovery)

ETag
string

Weak ETag for conditional request support (If-None-Match)

400

Section titled “400 ”

Invalid parameters (invalid plan_id format, unsupported year, SBM-only state)

RFC 9457 Problem Details for HTTP APIs (application/problem+json)

object
type
required

URI identifying the problem type. about:blank for standard HTTP status semantics.

string format: uri
title
required

Short human-readable summary of the problem type

string
status
required

HTTP status code

integer
detail
required

Human-readable explanation specific to this occurrence

string
instance

URI reference identifying the specific occurrence (request path)

string format: uri-reference
errors

Validation errors (extension member, present on 400 responses)

Array<object>
object
field

Dot-delimited path to the invalid field

string
message

Validation error message

string
required_tier

Minimum subscription tier required (extension member, present on 402 responses)

string
Allowed values: pro enterprise
upgrade

URL to upgrade subscription (extension member, present on 402/429 responses)

string format: uri
Example
{
  "type": "https://api.opelyx.com/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Plan 99999XX0000000-00 not found.",
  "instance": "/v1/health/plans/99999XX0000000-00"
}

401

Section titled “401 ”

Missing or invalid API key

RFC 9457 Problem Details for HTTP APIs (application/problem+json)

object
type
required

URI identifying the problem type. about:blank for standard HTTP status semantics.

string format: uri
title
required

Short human-readable summary of the problem type

string
status
required

HTTP status code

integer
detail
required

Human-readable explanation specific to this occurrence

string
instance

URI reference identifying the specific occurrence (request path)

string format: uri-reference
errors

Validation errors (extension member, present on 400 responses)

Array<object>
object
field

Dot-delimited path to the invalid field

string
message

Validation error message

string
required_tier

Minimum subscription tier required (extension member, present on 402 responses)

string
Allowed values: pro enterprise
upgrade

URL to upgrade subscription (extension member, present on 402/429 responses)

string format: uri
Example
{
  "type": "https://api.opelyx.com/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Plan 99999XX0000000-00 not found.",
  "instance": "/v1/health/plans/99999XX0000000-00"
}

Headers

Section titled “Headers ”
WWW-Authenticate
string

Bearer authentication challenge

402

Section titled “402 ”

Feature requires a higher-tier subscription

RFC 9457 Problem Details for HTTP APIs (application/problem+json)

object
type
required

URI identifying the problem type. about:blank for standard HTTP status semantics.

string format: uri
title
required

Short human-readable summary of the problem type

string
status
required

HTTP status code

integer
detail
required

Human-readable explanation specific to this occurrence

string
instance

URI reference identifying the specific occurrence (request path)

string format: uri-reference
errors

Validation errors (extension member, present on 400 responses)

Array<object>
object
field

Dot-delimited path to the invalid field

string
message

Validation error message

string
required_tier

Minimum subscription tier required (extension member, present on 402 responses)

string
Allowed values: pro enterprise
upgrade

URL to upgrade subscription (extension member, present on 402/429 responses)

string format: uri
Example
{
  "type": "https://api.opelyx.com/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Plan 99999XX0000000-00 not found.",
  "instance": "/v1/health/plans/99999XX0000000-00"
}

404

Section titled “404 ”

Plan not found in crosswalk data

RFC 9457 Problem Details for HTTP APIs (application/problem+json)

object
type
required

URI identifying the problem type. about:blank for standard HTTP status semantics.

string format: uri
title
required

Short human-readable summary of the problem type

string
status
required

HTTP status code

integer
detail
required

Human-readable explanation specific to this occurrence

string
instance

URI reference identifying the specific occurrence (request path)

string format: uri-reference
errors

Validation errors (extension member, present on 400 responses)

Array<object>
object
field

Dot-delimited path to the invalid field

string
message

Validation error message

string
required_tier

Minimum subscription tier required (extension member, present on 402 responses)

string
Allowed values: pro enterprise
upgrade

URL to upgrade subscription (extension member, present on 402/429 responses)

string format: uri
Example
{
  "type": "https://api.opelyx.com/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Plan 99999XX0000000-00 not found.",
  "instance": "/v1/health/plans/99999XX0000000-00"
}

429

Section titled “429 ”

Rate limit exceeded

RFC 9457 Problem Details for HTTP APIs (application/problem+json)

object
type
required

URI identifying the problem type. about:blank for standard HTTP status semantics.

string format: uri
title
required

Short human-readable summary of the problem type

string
status
required

HTTP status code

integer
detail
required

Human-readable explanation specific to this occurrence

string
instance

URI reference identifying the specific occurrence (request path)

string format: uri-reference
errors

Validation errors (extension member, present on 400 responses)

Array<object>
object
field

Dot-delimited path to the invalid field

string
message

Validation error message

string
required_tier

Minimum subscription tier required (extension member, present on 402 responses)

string
Allowed values: pro enterprise
upgrade

URL to upgrade subscription (extension member, present on 402/429 responses)

string format: uri
Example
{
  "type": "https://api.opelyx.com/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Plan 99999XX0000000-00 not found.",
  "instance": "/v1/health/plans/99999XX0000000-00"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds until the rate limit resets

RateLimit-Limit
integer

Maximum requests per day for this tier

RateLimit-Remaining
integer

Remaining requests today

RateLimit-Reset
integer

Unix timestamp when the limit resets (midnight UTC)