Retirement

HSA contribution limit + long-horizon projection

Returns the HSA contribution limit (with the last-month rule and month-based proration) and projects the balance over a horizon, with an optional triple-tax-advantage illustration versus a taxable account. Reuses the contribution-limits engine for the year-keyed HSA figures. Deterministic.

post/v1/retirement/hsa

Request

  • Base URL: https://api.numeratica.com
  • URL: https://api.numeratica.com/v1/retirement/hsa
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

tax_year2025 | 2026 required
coverage'self' | 'family' required
ageinteger required

55+ adds the catch-up.

months_eligibleinteger

HDHP-covered months (proration).

use_last_month_ruleboolean

Eligible on Dec 1 grants the full-year limit.

current_balancenumber
annual_contributionnumber
expected_returnnumber
yearsinteger
marginal_ratenumber

Optional; drives the tax-advantage illustration.

Example request

{
  "tax_year": 2026,
  "coverage": "family",
  "age": 55
}

Response

Limit + projection

result_idstring
engine_versionstring
disclaimerstring

Example response

{
  "result_id": "hsa_1a2b3c4d5e6f7a8b",
  "engine_version": "hsa-1.0.0",
  "inputs": {
    "tax_year": 2026,
    "coverage": "family",
    "age": 55
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.