Skip to content
Opelyx Docs

Side-by-side comparison of 2-4 plans

GET
/v1/health/plans/compare

Fetches full details and rates for 2-4 plans, returning them in _embedded.plans with a comparison_summary identifying the lowest-premium, lowest-deductible, and lowest-MOOP plans. Requires Pro or Enterprise subscription.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
ids
required
string

Comma-separated plan IDs (2-4)

Example
21989AK0030001-01,21989AK0030002-01
zip
required
string
/^\d{5}$/

5-digit ZIP code

Example
99501
age
required
integer
<= 65

Applicant age

Example
35
year
integer
default: 2026 >= 2014 <= 2030

Plan year. Defaults to 2026. Available: 2026

county_fips
string
/^\d{5}$/

5-digit county FIPS code to disambiguate ZIPs spanning multiple rating areas

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Plan comparison with HAL _embedded plans and summary

Side-by-side plan comparison with HAL _embedded plans

object
_links
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
_embedded
object
plans
Array<object>
>= 2 items <= 4 items

Abbreviated plan data returned in search and compare collections

object
_links

HAL links for this plan item

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
id

Plan variant ID

string
name

Marketing name

string
issuer

Insurance company name

string
state

Two-letter state code

string
metal_level
string
Allowed values: bronze expanded bronze silver gold platinum catastrophic
plan_type
string
Allowed values: hmo ppo epo pos indemnity
premium

Monthly premium for the given age

number
premium_with_credit

Premium after estimated APTC (null until subsidy calculation is available)

number
nullable
deductible

Cost amount for individual and family tiers

object
individual

Individual cost in dollars

number
family

Family cost in dollars

number
max_out_of_pocket

Cost amount for individual and family tiers

object
individual

Individual cost in dollars

number
family

Family cost in dollars

number
hsa_eligible
boolean
national_network
boolean
links

External resource URLs (SBC, formulary, etc.)

object
benefits_summary
string format: uri
nullable
brochure
string format: uri
nullable
formulary
string format: uri
nullable
provider_directory
string format: uri
nullable
comparison_summary
object
lowest_premium_plan_id
string
nullable
lowest_deductible_plan_id
string
lowest_moop_plan_id
string
hsa_eligible_count
integer
zip
string
state
string
county
string
county_fips
string
rating_area
string
multiple_areas
boolean
age
integer
plan_year
integer
data_source
string
data_freshness
string

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 ”

Validation error

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 ”

Resource not found

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)