Form 8889 Deduction Calculator: GET /api/v1/calculator/form-8889

For AI agents: this page is also Markdown at /developers/calculate-form8889.md. Every docs page is listed in /developers/llms.txt.

Calculate HSA deduction amounts for IRS Form 8889 filing based on coverage type and contributions.

GET /api/v1/calculator/form-8889

Parameters

Name	In	Required	Default	Description
`coverage`	query	no	`self`	Coverage type. Defaults to self. One of: self, family.
`age55`	query	no	`false`	Whether account holder is 55 or older (for catch-up contributions)
`directContributions`	query	no	`4400`	Direct contributions amount in USD
`employerContributions`	query	no	`0`	Employer contributions amount in USD (optional)
`age65`	query	no	`false`	Account holder was 65 or older (Line 17b penalty exception)
`totalDistributions`	query	no	`0`	Total HSA distributions in the year (Form 1099-SA box 1)
`qualifiedExpenses`	query	no	`0`	Unreimbursed qualified medical expenses paid from distributions
`rollovers`	query	no	`0`	Distributions rolled over or transferred to another HSA
`year`	query	no	`2026`	Tax year; must have published IRS limits

Example request

curl "https://www.hsatrackr.com/api/v1/calculator/form-8889?coverage=family&age55=false&directContributions=4400&employerContributions=2000"

Example response

A real response from the live handler.

{
  "data": {
    "inputs": {
      "year": 2026,
      "coverage": "family",
      "age55Plus": false,
      "age65Plus": false,
      "directContributions": 4400,
      "employerContributions": 2000,
      "totalDistributions": 0,
      "qualifiedExpenses": 0,
      "rollovers": 0
    },
    "limits": {
      "selfOnly": 4400,
      "family": 8750,
      "catchUp": 1000
    },
    "results": {
      "annualLimit": 8750,
      "catchUp": 0,
      "maxContribution": 8750,
      "totalContributions": 6400,
      "deductibleAmount": 4400,
      "excessContribution": 0,
      "taxableDistributions": 0,
      "penaltyAmount": 0
    }
  },
  "meta": {
    "source": "https://www.hsatrackr.com/guides/form-8889",
    "citation_url": "https://www.hsatrackr.com/guides/form-8889",
    "updated": "2026-01-01",
    "disclaimer": "This information is for educational purposes only and does not constitute tax, legal, or financial advice. Consult a qualified professional for your specific situation.",
    "api_docs": "https://www.hsatrackr.com/api/v1"
  }
}

Response fields

Every response is { data, meta }. meta.citation_url is the public page to cite.

Field	Type	Always present
`inputs`	object	yes
`limits`	object	yes
`results`	object	yes

Errors

Status	Meaning
`400`	Bad request - invalid parameters
`429`	Rate limit exceeded (30 requests per minute per IP)

Full contract: openapi.json. All endpoints: API overview.