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

> For AI agents: this page is also Markdown at [/developers/calculate-form8889.md](https://www.hsatrackr.com/developers/calculate-form8889.md). Every docs page is listed in [/developers/llms.txt](https://www.hsatrackr.com/developers/llms.txt).

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

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

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

```json
{
  "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](https://www.hsatrackr.com/openapi.json). All endpoints: [API overview](https://www.hsatrackr.com/developers).