---
title: "HSA contribution limit + long-horizon projection"
method: POST
path: "/v1/retirement/hsa"
tags: ["Retirement"]
---

# HSA contribution limit + long-horizon projection

`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`

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.

## Request body

- HSARequest
  - `tax_year` 2025 | 2026, required
  - `coverage` 'self' | 'family', required
  - `age` integer, required: 55+ adds the catch-up.
  - `months_eligible` integer: HDHP-covered months (proration).
  - `use_last_month_rule` boolean: Eligible on Dec 1 grants the full-year limit.
  - `current_balance` number
  - `annual_contribution` number
  - `expected_return` number
  - `years` integer
  - `marginal_rate` number: Optional; drives the tax-advantage illustration.

## Response `200`

Limit + projection

- HSAResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` HSARequest
    - `tax_year` 2025 | 2026, required
    - `coverage` 'self' | 'family', required
    - `age` integer, required: 55+ adds the catch-up.
    - `months_eligible` integer: HDHP-covered months (proration).
    - `use_last_month_rule` boolean: Eligible on Dec 1 grants the full-year limit.
    - `current_balance` number
    - `annual_contribution` number
    - `expected_return` number
    - `years` integer
    - `marginal_rate` number: Optional; drives the tax-advantage illustration.
  - `result` object
    - `contribution_limit` number: Full-year limit incl. 55+ catch-up.
    - `allowed_contribution` number: After last-month rule / proration.
    - `projected_balance` number: HSA, tax-free growth.
    - `contribution_tax_savings` number: Up-front deduction value (only when marginal_rate set).
    - `projected_taxable_equivalent` number: Same saving in a taxable account (only when marginal_rate set).
    - `hsa_advantage` number: HSA minus taxable equivalent (only when marginal_rate set).
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)