Skip to content
Opelyx Docs

Estimate APTC subsidy amount

GET
/v1/health/plans/aptc-estimate

Calculates the Advanced Premium Tax Credit (APTC) subsidy based on household income, size, and member ages. Uses the second-lowest cost Silver plan (SLCSP) as the benchmark. Implements ACA 3-child rule and state-adjusted FPL (Alaska, Hawaii). Requires Pro or Enterprise subscription.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
zip
required
string
/^\d{5}$/

5-digit ZIP code

Example
33125
household_income
required
number

Annual gross household income in dollars

Example
45000
household_size
required
integer
>= 1 <= 20

Total household members for FPL calculation

Example
3
ages
required
string

Comma-separated ages of members seeking marketplace coverage (0-65)

Example
35,33,5
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 ”

APTC subsidy estimate with household breakdown

APTC subsidy estimate with household breakdown and member rates

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
search

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
aptc_amount

Estimated monthly APTC amount in dollars

number
benchmark_premium

Total SLCSP benchmark premium for all eligible members

number
benchmark_plan_description
string
household
object
income
number
size
integer
fpl_percentage
number
applicable_percentage
number
expected_monthly_contribution
number
members
Array<object>
object
age
integer
slcsp_rate
number
eligibility
object
eligible
boolean
notes
Array<string>
zip
string
state
string
rating_area
string
plan_year
integer
data_freshness
string
data_source
string
disclaimer
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)