{ "openapi": "3.0.3", "info": { "title": "HSA Trackr API", "description": "Free, read-only API for HSA (Health Savings Account) data: expense eligibility rulings, contribution limits, provider comparisons, tax calculators and state HSA tax rules. No authentication. Limits come from IRS revenue procedures; eligibility rulings summarize IRS guidance, and those with a non-empty sourceBasis link their sources. Not tax advice. Docs: https://www.hsatrackr.com/developers", "version": "1.0.0", "contact": { "name": "HSA Trackr", "url": "https://www.hsatrackr.com", "email": "will.mather@mathermediasolutions.com" }, "license": { "name": "MIT" } }, "servers": [ { "url": "https://www.hsatrackr.com", "description": "Production" } ], "x-rate-limit": "30 requests per minute per IP address", "x-agent-examples": [ { "description": "Look up a qualified medical expense", "method": "GET", "url": "https://www.hsatrackr.com/api/v1/eligible?search=lasik&category=vision" }, { "description": "Retrieve the 2026 HSA contribution limits", "method": "GET", "url": "https://www.hsatrackr.com/api/v1/limits?year=2026" }, { "description": "Compare two HSA providers", "method": "GET", "url": "https://www.hsatrackr.com/api/v1/providers/compare?providers=fidelity,lively" } ], "tags": [ { "name": "Discovery", "description": "API documentation and index" }, { "name": "Contributions", "description": "HSA contribution limits and HDHP requirements" }, { "name": "Eligible Expenses", "description": "Search and view HSA-eligible medical expenses" }, { "name": "Glossary", "description": "HSA terminology and definitions" }, { "name": "Providers", "description": "HSA custodian providers and comparisons" }, { "name": "State Guides", "description": "State-specific HSA tax information" }, { "name": "Calculators", "description": "Tax savings, procedure cost, and Form 8889 calculators" } ], "paths": { "/api/v1": { "get": { "tags": [ "Discovery" ], "summary": "API Documentation Index", "description": "Returns documentation and list of all available endpoints.", "operationId": "getApiIndex", "responses": { "200": { "description": "API index and documentation", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string", "example": "1.0.0" }, "description": { "type": "string" }, "rate_limit": { "type": "string" }, "endpoints": { "type": "object", "properties": { "limits": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "params": { "type": "object", "properties": { "year": { "type": "string" } }, "required": [ "year" ] }, "example": { "type": "string" } }, "required": [ "path", "description", "params", "example" ] }, "eligible": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "params": { "type": "object", "properties": { "search": { "type": "string" }, "category": { "type": "string" }, "eligibility": { "type": "string" }, "limit": { "type": "string" }, "offset": { "type": "string" } }, "required": [ "search", "category", "eligibility", "limit", "offset" ] }, "example": { "type": "string" } }, "required": [ "path", "description", "params", "example" ] }, "eligible/check": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "params": { "type": "object", "properties": { "q": { "type": "string" } }, "required": [ "q" ] }, "example": { "type": "string" } }, "required": [ "path", "description", "params", "example" ] }, "eligible/:slug": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "example": { "type": "string" } }, "required": [ "path", "description", "example" ] }, "glossary": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "params": { "type": "object", "properties": { "search": { "type": "string" }, "category": { "type": "string" } }, "required": [ "search", "category" ] }, "example": { "type": "string" } }, "required": [ "path", "description", "params", "example" ] }, "glossary/:slug": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "example": { "type": "string" } }, "required": [ "path", "description", "example" ] }, "providers": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "example": { "type": "string" } }, "required": [ "path", "description", "example" ] }, "providers/:slug": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "example": { "type": "string" } }, "required": [ "path", "description", "example" ] }, "providers/compare": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "params": { "type": "object", "properties": { "providers": { "type": "string" } }, "required": [ "providers" ] }, "example": { "type": "string" } }, "required": [ "path", "description", "params", "example" ] }, "calculator/tax-savings": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "params": { "type": "object", "properties": { "contribution": { "type": "string" }, "federalBracket": { "type": "string" }, "stateRate": { "type": "string" }, "years": { "type": "string" }, "expectedReturn": { "type": "string" } }, "required": [ "contribution", "federalBracket", "stateRate", "years", "expectedReturn" ] }, "example": { "type": "string" } }, "required": [ "path", "description", "params", "example" ] }, "calculator/hsa-vs-cash/:procedure": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "params": { "type": "object", "properties": { "taxRate": { "type": "string" }, "years": { "type": "string" }, "returnRate": { "type": "string" } }, "required": [ "taxRate", "years", "returnRate" ] }, "example": { "type": "string" } }, "required": [ "path", "description", "params", "example" ] }, "calculator/form-8889": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "params": { "type": "object", "properties": { "coverage": { "type": "string" }, "age55": { "type": "string" }, "age65": { "type": "string" }, "directContributions": { "type": "string" }, "employerContributions": { "type": "string" }, "totalDistributions": { "type": "string" }, "qualifiedExpenses": { "type": "string" }, "rollovers": { "type": "string" }, "year": { "type": "string" } }, "required": [ "coverage", "age55", "age65", "directContributions", "employerContributions", "totalDistributions", "qualifiedExpenses", "rollovers", "year" ] }, "example": { "type": "string" } }, "required": [ "path", "description", "params", "example" ] }, "states/:slug": { "type": "object", "properties": { "path": { "type": "string" }, "description": { "type": "string" }, "example": { "type": "string" } }, "required": [ "path", "description", "example" ] } }, "required": [ "limits", "eligible", "eligible/check", "eligible/:slug", "glossary", "glossary/:slug", "providers", "providers/:slug", "providers/compare", "calculator/tax-savings", "calculator/hsa-vs-cash/:procedure", "calculator/form-8889", "states/:slug" ] } }, "required": [ "name", "version", "description", "rate_limit", "endpoints" ], "description": "example" }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "data": { "name": "HSA Trackr API", "version": "1.0", "description": "Free, public API for HSA (Health Savings Account) data including contribution limits, eligible expenses, glossary terms, provider comparisons, calculators, and state tax guides.", "rate_limit": "30 requests per minute per IP", "endpoints": { "limits": { "path": "/api/v1/limits", "description": "HSA contribution limits, HDHP requirements, and out-of-pocket maximums by year (2004-2026). Omit year to get every year.", "params": { "year": "optional, e.g. ?year=2026" }, "example": "/api/v1/limits?year=2026" }, "eligible": { "path": "/api/v1/eligible", "description": "233 HSA-eligible and ineligible medical expenses with categories, costs, and FAQs.", "params": { "search": "optional text search, e.g. ?search=lasik", "category": "optional filter: medical, dental, vision, pharmacy, mental-health, lab-tests, preventive-care, equipment-supplies", "eligibility": "optional filter: eligible, partially, ineligible", "limit": "optional page size, 1 to 100; omit to get every match", "offset": "optional number of results to skip, default 0" }, "example": "/api/v1/eligible?search=lasik&category=vision" }, "eligible/check": { "path": "/api/v1/eligible/check", "description": "Answer one question: is this item HSA eligible? Best match, match quality, up to 3 alternatives, and the sources behind the ruling.", "params": { "q": "required item in plain words, 2-120 characters" }, "example": "/api/v1/eligible/check?q=sunscreen" }, "eligible/:slug": { "path": "/api/v1/eligible/:slug", "description": "Single eligible expense by slug.", "example": "/api/v1/eligible/lasik" }, "glossary": { "path": "/api/v1/glossary", "description": "62 HSA-related terms with definitions, related terms, and FAQs.", "params": { "search": "optional text search, e.g. ?search=hdhp", "category": "optional filter: accounts, plans, contributions, expenses, taxes, strategies, providers" }, "example": "/api/v1/glossary?search=hdhp" }, "glossary/:slug": { "path": "/api/v1/glossary/:slug", "description": "Single glossary term by slug.", "example": "/api/v1/glossary/hsa" }, "providers": { "path": "/api/v1/providers", "description": "9 HSA providers with fees, investment options, interest rates, and features.", "example": "/api/v1/providers" }, "providers/:slug": { "path": "/api/v1/providers/:slug", "description": "Single HSA provider by slug.", "example": "/api/v1/providers/fidelity" }, "providers/compare": { "path": "/api/v1/providers/compare", "description": "Side-by-side comparison of 2+ HSA providers.", "params": { "providers": "required, comma-separated slugs, e.g. ?providers=fidelity,lively" }, "example": "/api/v1/providers/compare?providers=fidelity,lively" }, "calculator/tax-savings": { "path": "/api/v1/calculator/tax-savings", "description": "Calculate HSA tax savings including federal, state, and FICA benefits plus investment growth.", "params": { "contribution": "annual contribution in dollars (default: 4400)", "federalBracket": "federal tax bracket percentage (default: 22)", "stateRate": "state income tax rate percentage (default: 5)", "years": "years to grow (default: 10)", "expectedReturn": "expected annual return percentage (default: 7)" }, "example": "/api/v1/calculator/tax-savings?contribution=4400&federalBracket=22&stateRate=5&years=10" }, "calculator/hsa-vs-cash/:procedure": { "path": "/api/v1/calculator/hsa-vs-cash/:procedure", "description": "Compare paying for a medical procedure with HSA now vs investing and reimbursing later.", "params": { "taxRate": "combined tax rate percentage (default: 30)", "years": "years to defer reimbursement (default: 10)", "returnRate": "expected annual return percentage (default: 7)" }, "example": "/api/v1/calculator/hsa-vs-cash/lasik?taxRate=30&years=10" }, "calculator/form-8889": { "path": "/api/v1/calculator/form-8889", "description": "Calculate IRS Form 8889 HSA deduction and taxable distributions.", "params": { "coverage": "\"self\" or \"family\" (default: self)", "age55": "catch-up eligible (default: false)", "age65": "no penalty on non-qualified distributions (default: false)", "directContributions": "your direct contributions (default: 4400)", "employerContributions": "W-2 Box 12 Code W amount (default: 0)", "totalDistributions": "total distributions from 1099-SA (default: 0)", "qualifiedExpenses": "qualified medical expenses (default: 0)", "rollovers": "rollover amounts (default: 0)", "year": "tax year (default: 2026)" }, "example": "/api/v1/calculator/form-8889?coverage=self&age55=false&directContributions=4400" }, "states/:slug": { "path": "/api/v1/states/:slug", "description": "51 state HSA tax guides (50 states + DC). Use \"all\" for the full list.", "example": "/api/v1/states/california" } } }, "meta": { "source": "https://www.hsatrackr.com", "citation_url": "https://www.hsatrackr.com", "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" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/limits": { "get": { "tags": [ "Contributions" ], "summary": "HSA Contribution Limits", "description": "Get HSA contribution limits, HDHP minimum requirements, and out-of-pocket maximums for a specific year.", "operationId": "getContributionLimits", "parameters": [ { "name": "year", "in": "query", "description": "Tax year, 2004 to 2026. Omit to get every year.", "required": false, "schema": { "type": "integer", "minimum": 2004, "maximum": 2026, "example": 2026 } } ], "responses": { "200": { "description": "Contribution limits for the year", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "year": { "type": "integer" }, "selfOnly": { "type": "integer" }, "family": { "type": "integer" }, "catchUp": { "type": "integer" }, "oopMaxSelfOnly": { "type": "integer" }, "oopMaxFamily": { "type": "integer" }, "minDeductibleSelfOnly": { "type": "integer" }, "minDeductibleFamily": { "type": "integer" }, "notes": { "type": "string" } }, "required": [ "year", "selfOnly", "family", "catchUp", "oopMaxSelfOnly", "oopMaxFamily", "minDeductibleSelfOnly", "minDeductibleFamily", "notes" ], "description": "one year" }, { "type": "object", "properties": { "years": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "selfOnly": { "type": "integer" }, "family": { "type": "integer" }, "catchUp": { "type": "integer" }, "oopMaxSelfOnly": { "type": "integer" }, "oopMaxFamily": { "type": "integer" }, "minDeductibleSelfOnly": { "type": "integer" }, "minDeductibleFamily": { "type": "integer" }, "notes": { "type": "string" } }, "required": [ "year", "selfOnly", "family", "catchUp", "oopMaxSelfOnly", "oopMaxFamily", "minDeductibleSelfOnly", "minDeductibleFamily", "notes" ] } }, "availableYears": { "type": "array", "items": { "type": "integer" } } }, "required": [ "years", "availableYears" ], "description": "every year (year omitted)" } ] }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "data": { "year": 2026, "selfOnly": 4400, "family": 8750, "catchUp": 1000, "oopMaxSelfOnly": 8500, "oopMaxFamily": 17000, "minDeductibleSelfOnly": 1700, "minDeductibleFamily": 3400, "notes": "IRS Rev. Proc. 2025-19 (https://www.irs.gov/pub/irs-drop/rp-25-19.pdf). Effective for tax year 2026. Sources checked October 8, 2026." }, "meta": { "source": "https://www.hsatrackr.com/limits", "citation_url": "https://www.hsatrackr.com/limits", "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" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/eligible": { "get": { "tags": [ "Eligible Expenses" ], "summary": "Search HSA-Eligible Expenses", "description": "Search and filter every canonical HSA expense eligibility decision (the total is in data.pagination.total). Returns paginated results with eligible, partially eligible, and ineligible status, typical costs, and documentation requirements.", "operationId": "listEligibleExpenses", "parameters": [ { "name": "search", "in": "query", "description": "Search term (name or description)", "required": false, "schema": { "type": "string", "example": "lasik" } }, { "name": "category", "in": "query", "description": "Filter by expense category.", "required": false, "schema": { "type": "string", "enum": [ "medical", "dental", "vision", "pharmacy", "mental-health", "lab-tests", "preventive-care", "equipment-supplies" ], "example": "vision" } }, { "name": "eligibility", "in": "query", "required": false, "description": "Filter by eligibility status", "schema": { "type": "string", "enum": [ "eligible", "partially", "ineligible" ] } }, { "name": "limit", "in": "query", "description": "Results per page, 1 to 100. Omit to get every match.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of results to skip for pagination", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List of eligible expenses", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "expenses": { "type": "array", "items": { "$ref": "#/components/schemas/EligibleExpense" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Page size used (the match count when limit was omitted)" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean", "description": "True when another page exists at offset + limit" } }, "required": [ "limit", "offset", "total", "hasMore" ] }, "total": { "type": "integer", "description": "Matches before pagination" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "slug", "name", "description" ] } } }, "required": [ "expenses", "pagination", "total", "categories" ] }, "meta": { "$ref": "#/components/schemas/MetaInfo" } }, "required": [ "data", "meta" ] }, "example": { "data": { "expenses": [ { "slug": "lasik", "name": "LASIK Eye Surgery", "category": "vision", "eligibility": "eligible", "description": "LASIK and other corrective eye surgery is HSA-eligible.", "details": "LASIK, PRK, SMILE, and other laser vision correction surgeries are qualified medical expenses. Pre-operative consultations, the surgery itself, and post-operative care visits are all eligible. Enhancement or touch-up procedures also qualify. Medicated eye drops prescribed after surgery are a separate eligible expense.", "requirements": "Must be performed by a licensed ophthalmologist or eye surgeon. A pre-operative exam confirming candidacy is standard.", "commonCost": "$2,000–$4,000 per eye", "faqs": [ { "question": "Is LASIK HSA-eligible?", "answer": "Yes. LASIK and all corrective eye surgeries are fully HSA-eligible." }, { "question": "Is PRK HSA-eligible?", "answer": "Yes. PRK and other laser vision correction procedures are eligible." } ], "relatedSlugs": [ "eye-exam", "prescription-glasses" ], "benefitCallout": { "taxSavingsExample": "LASIK for both eyes at $4,000-$8,000 total - HSA saves $880-$1,760 at the 22% bracket (additional savings via FICA when paid through payroll deduction)", "strategyTip": "LASIK is one of the best shoebox strategy expenses. Pay out of pocket and let your HSA grow tax-free for years before reimbursing." } } ], "total": 1, "pagination": { "limit": 1, "offset": 0, "total": 1, "hasMore": false }, "categories": [ { "slug": "medical", "name": "Medical", "description": "Doctor visits, surgeries, hospital stays, and general medical care." }, { "slug": "dental", "name": "Dental", "description": "Dental care including cleanings, fillings, braces, and oral surgery." } ] }, "meta": { "source": "https://www.hsatrackr.com/eligible", "citation_url": "https://www.hsatrackr.com/eligible", "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" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/eligible/check": { "get": { "tags": [ "Eligible Expenses" ], "summary": "Check One Item", "operationId": "checkEligibility", "description": "Answer one question: is this item HSA eligible? Returns the best matching ruling, how strong the match is, up to 3 alternatives, and the sources behind the ruling. Built for CLIs, browser extensions and integrations.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "The item to check, in plain words or as a question (2 to 120 characters). Question words like \"is\", \"can I use my HSA for\" and \"HSA eligible\" are ignored.", "schema": { "type": "string", "minLength": 2, "maxLength": 120, "example": "ozempic" } } ], "responses": { "200": { "description": "Best match and alternatives", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "query": { "type": "string", "description": "The q you sent, trimmed" }, "found": { "type": "boolean", "description": "True only for an exact or strong match. False means no answer; check alternatives" }, "matchQuality": { "type": "string", "nullable": true, "enum": [ "exact", "strong", null ], "description": "exact: name, slug or alias. strong: the name or its key words. null when found is false" }, "match": { "allOf": [ { "$ref": "#/components/schemas/EligibilityCheckItem" } ], "nullable": true, "description": "The ruling that answers the question, or null when found is false" }, "alternatives": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/EligibilityCheckItem" }, { "type": "object", "properties": { "matchQuality": { "type": "string", "enum": [ "exact", "strong", "weak" ] } }, "required": [ "matchQuality" ] } ] }, "description": "Up to 3 other rulings, including weak suggestions when found is false", "maxItems": 3 }, "searchUrl": { "type": "string", "format": "uri", "description": "The full search on hsatrackr.com for this query" } }, "required": [ "query", "found", "matchQuality", "match", "alternatives", "searchUrl" ] }, "meta": { "$ref": "#/components/schemas/MetaInfo" } }, "required": [ "data", "meta" ] }, "example": { "data": { "query": "ozempic", "found": true, "matchQuality": "exact", "match": { "slug": "ozempic", "name": "GLP-1 Prescription Medications", "category": "pharmacy", "eligibility": "eligible", "description": "Prescribed GLP-1 medicines such as Ozempic, Wegovy, Mounjaro, and Zepbound are HSA-eligible prescription drug expenses.", "requirements": "Keep the valid prescription and itemized pharmacy receipt, and subtract any insurance or other reimbursement. For a compounded product, confirm that it was prescribed for you and dispensed by a state-licensed pharmacy. HSA eligibility does not establish FDA approval, product quality, or legality.", "sourceBasis": [ { "label": "IRS Publication 502: Medicines", "url": "https://www.irs.gov/publications/p502", "supports": "Amounts paid for medicines and drugs prescribed for an individual are includible medical expenses.", "reviewedDate": "2026-07-14" }, { "label": "IRS Publication 969: Qualified medical expenses", "url": "https://www.irs.gov/publications/p969", "supports": "HSA distributions are tax-free only for uncompensated qualified medical expenses incurred after the HSA was established.", "reviewedDate": "2026-07-14" } ], "url": "https://www.hsatrackr.com/eligible/ozempic" }, "alternatives": [], "searchUrl": "https://www.hsatrackr.com/eligible?search=ozempic" }, "meta": { "source": "https://www.hsatrackr.com/eligible/ozempic", "citation_url": "https://www.hsatrackr.com/eligible/ozempic", "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" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/eligible/{slug}": { "get": { "tags": [ "Eligible Expenses" ], "summary": "Get Single Expense Detail", "description": "Retrieve detailed information about a specific HSA-eligible expense, including FAQs, related expenses, and special considerations.", "operationId": "getEligibleExpense", "parameters": [ { "name": "slug", "in": "path", "description": "Expense slug identifier (e.g., 'lasik', 'chiropractor', 'covid-tests')", "required": true, "schema": { "type": "string", "example": "lasik" } } ], "responses": { "200": { "description": "Detailed expense information", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EligibleExpenseDetail" }, "meta": { "$ref": "#/components/schemas/MetaInfo" } }, "required": [ "data", "meta" ] }, "example": { "data": { "slug": "lasik", "name": "LASIK Eye Surgery", "category": "vision", "eligibility": "eligible", "description": "LASIK and other corrective eye surgery is HSA-eligible.", "details": "LASIK, PRK, SMILE, and other laser vision correction surgeries are qualified medical expenses. Pre-operative consultations, the surgery itself, and post-operative care visits are all eligible. Enhancement or touch-up procedures also qualify. Medicated eye drops prescribed after surgery are a separate eligible expense.", "requirements": "Must be performed by a licensed ophthalmologist or eye surgeon. A pre-operative exam confirming candidacy is standard.", "commonCost": "$2,000–$4,000 per eye", "faqs": [ { "question": "Is LASIK HSA-eligible?", "answer": "Yes. LASIK and all corrective eye surgeries are fully HSA-eligible." }, { "question": "Is PRK HSA-eligible?", "answer": "Yes. PRK and other laser vision correction procedures are eligible." } ], "relatedSlugs": [ "eye-exam", "prescription-glasses" ], "benefitCallout": { "taxSavingsExample": "LASIK for both eyes at $4,000-$8,000 total - HSA saves $880-$1,760 at the 22% bracket (additional savings via FICA when paid through payroll deduction)", "strategyTip": "LASIK is one of the best shoebox strategy expenses. Pay out of pocket and let your HSA grow tax-free for years before reimbursing." } }, "meta": { "source": "https://www.hsatrackr.com/eligible/lasik", "citation_url": "https://www.hsatrackr.com/eligible/lasik", "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" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/glossary": { "get": { "tags": [ "Glossary" ], "summary": "Search Glossary Terms", "description": "Search and filter HSA-related glossary terms and definitions.", "operationId": "listGlossaryTerms", "parameters": [ { "name": "search", "in": "query", "description": "Search term (term name or definition)", "required": false, "schema": { "type": "string", "example": "hdhp" } }, { "name": "category", "in": "query", "description": "Filter by category.", "required": false, "schema": { "type": "string", "enum": [ "accounts", "plans", "contributions", "expenses", "taxes", "strategies", "providers" ], "example": "plans" } } ], "responses": { "200": { "description": "List of glossary terms", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "terms": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "term": { "type": "string" }, "shortDefinition": { "type": "string" }, "fullDefinition": { "type": "string" }, "relatedTerms": { "type": "array", "items": { "type": "string" } }, "relatedExpenses": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "faqs": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "question", "answer" ] } }, "seoTitle": { "type": "string" }, "seoDescription": { "type": "string" } }, "required": [ "slug", "term", "shortDefinition", "fullDefinition", "relatedTerms", "relatedExpenses", "category", "faqs" ] } }, "total": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "slug", "name", "description" ] } } }, "required": [ "terms", "total", "categories" ], "description": "terms" }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "data": { "terms": [ { "slug": "hdhp", "term": "High-Deductible Health Plan (HDHP)", "shortDefinition": "A health insurance plan with a higher deductible and lower premiums that qualifies you to open an HSA.", "fullDefinition": "A High-Deductible Health Plan (HDHP) is a health insurance plan with a higher annual deductible than traditional plans. In exchange for the higher deductible, HDHPs typically have lower monthly premiums. Most importantly, having an HDHP is the only way to qualify for opening a Health Savings Account (HSA).\n\nFor 2024, a plan qualifies as an HDHP if it has a minimum deductible of $1,600 for individual coverage or $3,200 for family coverage. Maximum out-of-pocket limits are $8,050 for individuals and $16,100 for families. These numbers are adjusted annually for inflation.\n\nHDHPs must cover preventive care before the deductible is met. This includes annual physicals, vaccinations, and certain screenings. For other care, you'll pay the full cost until you meet your deductible, then typically pay coinsurance until you hit your out-of-pocket maximum.", "relatedTerms": [ "hsa", "deductible" ], "category": "plans", "faqs": [ { "question": "What makes a plan an HDHP?", "answer": "For 2024, an HDHP must have a minimum deductible of $1,600 (individual) or $3,200 (family), and maximum out-of-pocket of $8,050 (individual) or $16,100 (family)." }, { "question": "Are HDHPs good for everyone?", "answer": "HDHPs work well for healthy people who don't use much healthcare and want to save on premiums while building HSA savings. They may not be ideal for people with chronic conditions or frequent medical needs." } ], "relatedExpenses": [] } ], "total": 1, "categories": [ { "slug": "accounts", "name": "Account Types", "description": "Different health savings and spending accounts" }, { "slug": "plans", "name": "Insurance Plans", "description": "Health insurance plans and coverage terms" } ] }, "meta": { "source": "https://www.hsatrackr.com/glossary", "citation_url": "https://www.hsatrackr.com/glossary", "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" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/glossary/{slug}": { "get": { "tags": [ "Glossary" ], "summary": "Get Single Glossary Term", "description": "Retrieve detailed information about a specific HSA glossary term.", "operationId": "getGlossaryTerm", "parameters": [ { "name": "slug", "in": "path", "description": "Glossary term slug (e.g., 'hsa', 'hdhp', 'deductible')", "required": true, "schema": { "type": "string", "example": "hdhp" } } ], "responses": { "200": { "description": "Glossary term definition and details", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "slug": { "type": "string" }, "term": { "type": "string" }, "shortDefinition": { "type": "string" }, "fullDefinition": { "type": "string" }, "relatedTerms": { "type": "array", "items": { "type": "string" } }, "relatedExpenses": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "faqs": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "question", "answer" ] } }, "seoTitle": { "type": "string" }, "seoDescription": { "type": "string" } }, "required": [ "slug", "term", "shortDefinition", "fullDefinition", "relatedTerms", "relatedExpenses", "category", "faqs" ], "description": "term" }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "data": { "slug": "hdhp", "term": "High-Deductible Health Plan (HDHP)", "shortDefinition": "A health insurance plan with a higher deductible and lower premiums that qualifies you to open an HSA.", "fullDefinition": "A High-Deductible Health Plan (HDHP) is a health insurance plan with a higher annual deductible than traditional plans. In exchange for the higher deductible, HDHPs typically have lower monthly premiums. Most importantly, having an HDHP is the only way to qualify for opening a Health Savings Account (HSA).\n\nFor 2024, a plan qualifies as an HDHP if it has a minimum deductible of $1,600 for individual coverage or $3,200 for family coverage. Maximum out-of-pocket limits are $8,050 for individuals and $16,100 for families. These numbers are adjusted annually for inflation.\n\nHDHPs must cover preventive care before the deductible is met. This includes annual physicals, vaccinations, and certain screenings. For other care, you'll pay the full cost until you meet your deductible, then typically pay coinsurance until you hit your out-of-pocket maximum.", "relatedTerms": [ "hsa", "deductible" ], "category": "plans", "faqs": [ { "question": "What makes a plan an HDHP?", "answer": "For 2024, an HDHP must have a minimum deductible of $1,600 (individual) or $3,200 (family), and maximum out-of-pocket of $8,050 (individual) or $16,100 (family)." }, { "question": "Are HDHPs good for everyone?", "answer": "HDHPs work well for healthy people who don't use much healthcare and want to save on premiums while building HSA savings. They may not be ideal for people with chronic conditions or frequent medical needs." } ], "relatedExpenses": [] }, "meta": { "source": "https://www.hsatrackr.com/glossary/hdhp", "citation_url": "https://www.hsatrackr.com/glossary/hdhp", "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" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/providers": { "get": { "tags": [ "Providers" ], "summary": "List HSA Providers", "description": "Get list of major HSA custodian providers with fee structures, investment options, and key features.", "operationId": "listProviders", "responses": { "200": { "description": "List of HSA providers", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "website": { "type": "string" }, "monthlyFee": { "type": "string" }, "investmentOptions": { "type": "string" }, "investmentMinimum": { "type": "string" }, "investingFeesSource": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ] }, "interestRate": { "type": "string" }, "fdic": { "type": "boolean" }, "mobileApp": { "type": "boolean" }, "debitCard": { "type": "boolean" }, "pros": { "type": "array", "items": { "type": "string" } }, "cons": { "type": "array", "items": { "type": "string" } }, "bestFor": { "type": "string" }, "description": { "type": "string" }, "feeCheckedAt": { "type": "string" } }, "required": [ "slug", "name", "type", "website", "monthlyFee", "investmentOptions", "investmentMinimum", "interestRate", "fdic", "mobileApp", "debitCard", "pros", "cons", "bestFor", "description" ] } }, "total": { "type": "integer" } }, "required": [ "providers", "total" ], "description": "example" }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "data": { "providers": [ { "slug": "lively", "name": "Lively", "type": "benefits", "website": "https://livelyme.pxf.io/L0qXyV", "monthlyFee": "$0", "investmentOptions": "Schwab self-directed brokerage or Devenir guided portfolios", "investmentMinimum": "$0", "investingFeesSource": { "label": "Source: Lively, checked October 16, 2026", "url": "https://livelyme.com/individual-hsa/invest-your-lively-hsa" }, "interestRate": "0.01%–0.02% APY", "fdic": true, "mobileApp": true, "debitCard": true, "pros": [ "No monthly maintenance fees", "Modern, user-friendly interface" ], "cons": [ "Schwab self-directed: $24 a year, or $0 at $3,000 and up. Schwab fees may apply.", "Guided Portfolio (Devenir): 0.50% a year on invested assets" ], "bestFor": "People who want cash and investing in one app, with no account fees", "description": "Lively is a benefits platform with a clean, modern HSA and no monthly fees. They offer both self-directed investing through Schwab and guided portfolios through Devenir." }, { "slug": "fidelity", "name": "Fidelity HSA", "type": "brokerage", "website": "https://www.fidelity.com/go/hsa/why-hsa", "monthlyFee": "$0", "investmentOptions": "Full brokerage access - stocks, ETFs, mutual funds, bonds", "investmentMinimum": "$0", "interestRate": "0.82% APY (as of Jan 2026)", "fdic": false, "mobileApp": true, "debitCard": true, "pros": [ "No account fees, trading fees, or investment minimums", "Full access to Fidelity's brokerage platform" ], "cons": [ "Not FDIC insured (SIPC protected)", "Must transfer out of employer HSA to use" ], "bestFor": "Hands-on investors who want $0 fees and full brokerage access", "description": "Fidelity offers one of the best HSAs for investors with zero account fees, zero trading fees, and full access to their brokerage platform. Consistently rated the top HSA by Morningstar for both spending and investing use cases." } ], "total": 9 }, "meta": { "source": "https://www.hsatrackr.com/compare", "citation_url": "https://www.hsatrackr.com/compare", "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" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/providers/{slug}": { "get": { "tags": [ "Providers" ], "summary": "Get Single Provider Detail", "description": "Retrieve detailed information about a specific HSA custodian provider.", "operationId": "getProvider", "parameters": [ { "name": "slug", "in": "path", "description": "Provider slug, for example fidelity, lively or optum-bank. GET /api/v1/providers lists them all.", "required": true, "schema": { "type": "string", "example": "fidelity" } } ], "responses": { "200": { "description": "Detailed provider information", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "website": { "type": "string" }, "monthlyFee": { "type": "string" }, "investmentOptions": { "type": "string" }, "investmentMinimum": { "type": "string" }, "investingFeesSource": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ] }, "interestRate": { "type": "string" }, "fdic": { "type": "boolean" }, "mobileApp": { "type": "boolean" }, "debitCard": { "type": "boolean" }, "pros": { "type": "array", "items": { "type": "string" } }, "cons": { "type": "array", "items": { "type": "string" } }, "bestFor": { "type": "string" }, "description": { "type": "string" }, "feeCheckedAt": { "type": "string" } }, "required": [ "slug", "name", "type", "website", "monthlyFee", "investmentOptions", "investmentMinimum", "interestRate", "fdic", "mobileApp", "debitCard", "pros", "cons", "bestFor", "description" ], "description": "provider" }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "data": { "slug": "fidelity", "name": "Fidelity HSA", "type": "brokerage", "website": "https://www.fidelity.com/go/hsa/why-hsa", "monthlyFee": "$0", "investmentOptions": "Full brokerage access - stocks, ETFs, mutual funds, bonds", "investmentMinimum": "$0", "interestRate": "0.82% APY (as of Jan 2026)", "fdic": false, "mobileApp": true, "debitCard": true, "pros": [ "No account fees, trading fees, or investment minimums", "Full access to Fidelity's brokerage platform" ], "cons": [ "Not FDIC insured (SIPC protected)", "Must transfer out of employer HSA to use" ], "bestFor": "Hands-on investors who want $0 fees and full brokerage access", "description": "Fidelity offers one of the best HSAs for investors with zero account fees, zero trading fees, and full access to their brokerage platform. Consistently rated the top HSA by Morningstar for both spending and investing use cases." }, "meta": { "source": "https://www.hsatrackr.com/compare", "citation_url": "https://www.hsatrackr.com/compare", "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" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/providers/compare": { "get": { "tags": [ "Providers" ], "summary": "Compare Providers", "description": "Side-by-side comparison of multiple HSA providers. Pass comma-separated provider slugs.", "operationId": "compareProviders", "parameters": [ { "name": "providers", "in": "query", "description": "Two or more provider slugs, comma-separated. Unknown slugs are listed in invalidSlugs.", "required": true, "schema": { "type": "string", "example": "fidelity,lively,optum-bank" } } ], "responses": { "200": { "description": "Provider comparison matrix", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "website": { "type": "string" }, "monthlyFee": { "type": "string" }, "investmentOptions": { "type": "string" }, "investmentMinimum": { "type": "string" }, "investingFeesSource": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ] }, "interestRate": { "type": "string" }, "fdic": { "type": "boolean" }, "mobileApp": { "type": "boolean" }, "debitCard": { "type": "boolean" }, "pros": { "type": "array", "items": { "type": "string" } }, "cons": { "type": "array", "items": { "type": "string" } }, "bestFor": { "type": "string" }, "description": { "type": "string" }, "feeCheckedAt": { "type": "string" } }, "required": [ "slug", "name", "type", "website", "monthlyFee", "investmentOptions", "investmentMinimum", "interestRate", "fdic", "mobileApp", "debitCard", "pros", "cons", "bestFor", "description" ] } }, "comparedCount": { "type": "integer" }, "invalidSlugs": { "type": "array", "items": { "type": "string" } } }, "required": [ "providers", "comparedCount" ], "description": "comparison" }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "data": { "providers": [ { "slug": "fidelity", "name": "Fidelity HSA", "type": "brokerage", "website": "https://www.fidelity.com/go/hsa/why-hsa", "monthlyFee": "$0", "investmentOptions": "Full brokerage access - stocks, ETFs, mutual funds, bonds", "investmentMinimum": "$0", "interestRate": "0.82% APY (as of Jan 2026)", "fdic": false, "mobileApp": true, "debitCard": true, "pros": [ "No account fees, trading fees, or investment minimums", "Full access to Fidelity's brokerage platform" ], "cons": [ "Not FDIC insured (SIPC protected)", "Must transfer out of employer HSA to use" ], "bestFor": "Hands-on investors who want $0 fees and full brokerage access", "description": "Fidelity offers one of the best HSAs for investors with zero account fees, zero trading fees, and full access to their brokerage platform. Consistently rated the top HSA by Morningstar for both spending and investing use cases." }, { "slug": "lively", "name": "Lively", "type": "benefits", "website": "https://livelyme.pxf.io/L0qXyV", "monthlyFee": "$0", "investmentOptions": "Schwab self-directed brokerage or Devenir guided portfolios", "investmentMinimum": "$0", "investingFeesSource": { "label": "Source: Lively, checked October 16, 2026", "url": "https://livelyme.com/individual-hsa/invest-your-lively-hsa" }, "interestRate": "0.01%–0.02% APY", "fdic": true, "mobileApp": true, "debitCard": true, "pros": [ "No monthly maintenance fees", "Modern, user-friendly interface" ], "cons": [ "Schwab self-directed: $24 a year, or $0 at $3,000 and up. Schwab fees may apply.", "Guided Portfolio (Devenir): 0.50% a year on invested assets" ], "bestFor": "People who want cash and investing in one app, with no account fees", "description": "Lively is a benefits platform with a clean, modern HSA and no monthly fees. They offer both self-directed investing through Schwab and guided portfolios through Devenir." } ], "comparedCount": 3 }, "meta": { "source": "https://www.hsatrackr.com/compare", "citation_url": "https://www.hsatrackr.com/compare", "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" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/states/{slug}": { "get": { "tags": [ "State Guides" ], "summary": "Get State HSA Tax Guide", "description": "Retrieve state-specific HSA tax information. Use 'all' as slug to get full list of all states.", "operationId": "getStateGuide", "parameters": [ { "name": "slug", "in": "path", "description": "State slug in lowercase (e.g., 'california', 'texas') or 'all' for full list", "required": true, "schema": { "type": "string", "example": "california" } } ], "responses": { "200": { "description": "State tax guide or list of all states", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "abbreviation": { "type": "string" }, "taxTreatment": { "type": "string" }, "incomeTaxRate": { "type": "string" }, "hasStateTax": { "type": "boolean" }, "summary": { "type": "string" }, "details": { "type": "string" }, "notes": { "type": "string", "nullable": true } }, "required": [ "slug", "name", "abbreviation", "taxTreatment", "incomeTaxRate", "hasStateTax", "summary", "details", "notes" ], "description": "state" }, { "type": "object", "properties": { "states": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "abbreviation": { "type": "string" }, "taxTreatment": { "type": "string" }, "incomeTaxRate": { "type": "string" }, "hasStateTax": { "type": "boolean" }, "summary": { "type": "string" } }, "required": [ "slug", "name", "abbreviation", "taxTreatment", "incomeTaxRate", "hasStateTax", "summary" ] } }, "total": { "type": "integer" } }, "required": [ "states", "total" ], "description": "all states (slug=all)" } ] }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "data": { "slug": "california", "name": "California", "abbreviation": "CA", "taxTreatment": "none", "incomeTaxRate": "1%–13.3%", "hasStateTax": true, "summary": "California does NOT recognize HSA tax benefits. Contributions are taxed, and investment gains are taxable income.", "details": "California does not conform to federal HSA tax treatment. HSA contributions are not deductible on your California state tax return. Investment earnings within the HSA are subject to California income tax and must be reported annually. Qualified withdrawals for medical expenses are still tax-free at the federal level, but you've already been taxed on the contributions and earnings at the state level. California treats HSAs similarly to regular investment accounts for state tax purposes.", "notes": "California residents should track HSA investment gains for state tax reporting. Consider the state tax impact when deciding contribution amounts." }, "meta": { "source": "https://www.hsatrackr.com/states/california", "citation_url": "https://www.hsatrackr.com/states/california", "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" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/calculator/tax-savings": { "get": { "tags": [ "Calculators" ], "summary": "Tax Savings Calculator", "description": "Calculate projected tax savings from HSA contributions based on tax bracket and years of contribution. Savings include 7.65% FICA, which only applies when you contribute through payroll; direct contributions save income tax only.", "operationId": "calculateTaxSavings", "parameters": [ { "name": "contribution", "in": "query", "description": "Annual contribution in USD (0 to 100,000)", "required": false, "schema": { "type": "number", "example": 4400, "default": 4400, "minimum": 0, "maximum": 100000 } }, { "name": "federalBracket", "in": "query", "description": "Federal tax bracket, percent (0 to 50)", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 50, "example": 24, "default": 22 } }, { "name": "stateRate", "in": "query", "description": "State income tax rate, percent (0 to 15)", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 15, "example": 9.3, "default": 5 } }, { "name": "years", "in": "query", "description": "Years to project (1 to 50)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "example": 30, "default": 10 } }, { "name": "expectedReturn", "in": "query", "required": false, "description": "Assumed annual investment return, percent (0 to 30)", "schema": { "type": "number", "default": 7, "minimum": 0, "maximum": 30 } } ], "responses": { "200": { "description": "Tax savings projection", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "inputs": { "type": "object", "properties": { "annualContribution": { "type": "integer" }, "federalBracket": { "type": "string" }, "stateRate": { "type": "string" }, "yearsToGrow": { "type": "integer" }, "expectedReturn": { "type": "string" } }, "required": [ "annualContribution", "federalBracket", "stateRate", "yearsToGrow", "expectedReturn" ] }, "results": { "type": "object", "properties": { "federalSavings": { "type": "integer" }, "stateSavings": { "type": "integer" }, "ficaSavings": { "type": "integer" }, "annualTaxSavings": { "type": "integer" }, "totalContributions": { "type": "integer" }, "totalTaxSavings": { "type": "integer" }, "investmentValue": { "type": "integer" }, "investmentGrowth": { "type": "integer" }, "taxableAccountValue": { "type": "integer" }, "advantageVsTaxable": { "type": "integer" } }, "required": [ "federalSavings", "stateSavings", "ficaSavings", "annualTaxSavings", "totalContributions", "totalTaxSavings", "investmentValue", "investmentGrowth", "taxableAccountValue", "advantageVsTaxable" ] } }, "required": [ "inputs", "results" ], "description": "result" }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "data": { "inputs": { "annualContribution": 4400, "federalBracket": "24%", "stateRate": "9.3%", "yearsToGrow": 30, "expectedReturn": "7%" }, "results": { "federalSavings": 1056, "stateSavings": 409, "ficaSavings": 337, "annualTaxSavings": 1802, "totalContributions": 132000, "totalTaxSavings": 54054, "investmentValue": 415627, "investmentGrowth": 283627, "taxableAccountValue": 203610, "advantageVsTaxable": 212017 } }, "meta": { "source": "https://www.hsatrackr.com/calculators/tax-savings", "citation_url": "https://www.hsatrackr.com/calculators/tax-savings", "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" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/calculator/hsa-vs-cash/{procedure}": { "get": { "tags": [ "Calculators" ], "summary": "HSA vs Cash Cost Comparison", "description": "Compare the cost of paying for a medical procedure with HSA funds vs out-of-pocket cash, including tax impact over time.", "operationId": "calculateHsaVsCash", "parameters": [ { "name": "procedure", "in": "path", "description": "Procedure slug.", "required": true, "schema": { "type": "string", "example": "lasik", "enum": [ "lasik", "braces", "dental-implants", "fertility-treatment", "knee-surgery", "hip-replacement", "wisdom-teeth-removal", "root-canal", "hearing-aids", "physical-therapy-series", "childbirth-delivery", "therapy-annual", "dermatology-treatment", "allergy-testing", "sleep-study", "back-surgery", "cataract-surgery", "dental-crown", "prescription-glasses", "mri-scan" ] } }, { "name": "taxRate", "in": "query", "description": "Combined federal and state tax rate, percent (0 to 60)", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 60, "example": 33.3, "default": 30 } }, { "name": "years", "in": "query", "description": "Years until you reimburse yourself (1 to 50)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "example": 5, "default": 10 } }, { "name": "returnRate", "in": "query", "required": false, "description": "Assumed annual investment return, percent (0 to 30)", "schema": { "type": "number", "default": 7, "minimum": 0, "maximum": 30 } } ], "responses": { "200": { "description": "HSA vs cash cost comparison", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "procedure": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "costRange": { "type": "object", "properties": { "low": { "type": "integer" }, "high": { "type": "integer" }, "typical": { "type": "integer" } }, "required": [ "low", "high", "typical" ] }, "description": { "type": "string" }, "eligibleSlug": { "type": "string" }, "faqs": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "question", "answer" ] } } }, "required": [ "slug", "name", "category", "costRange", "description", "eligibleSlug", "faqs" ] }, "calculation": { "type": "object", "properties": { "inputs": { "type": "object", "properties": { "typicalCost": { "type": "integer" }, "taxRate": { "type": "string" }, "years": { "type": "integer" }, "annualReturn": { "type": "string" } }, "required": [ "typicalCost", "taxRate", "years", "annualReturn" ] }, "results": { "type": "object", "properties": { "futureValue": { "type": "integer" }, "investmentGrowth": { "type": "integer" }, "taxSavings": { "type": "integer" }, "totalBenefit": { "type": "integer" } }, "required": [ "futureValue", "investmentGrowth", "taxSavings", "totalBenefit" ] } }, "required": [ "inputs", "results" ] } }, "required": [ "procedure", "calculation" ], "description": "procedure" }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "data": { "procedure": { "slug": "lasik", "name": "LASIK Eye Surgery", "category": "vision", "costRange": { "low": 4000, "high": 6000, "typical": 5000 }, "description": "LASIK is a popular vision correction surgery that reshapes the cornea to reduce or eliminate the need for glasses or contacts. Most patients pay out of pocket since insurance rarely covers it.", "eligibleSlug": "lasik", "faqs": [ { "question": "Is LASIK HSA-eligible?", "answer": "Yes. LASIK eye surgery is a qualified medical expense under IRS rules. You can pay with your HSA debit card or reimburse yourself later." }, { "question": "Can I reimburse myself for LASIK years later?", "answer": "Yes. As long as you had your HSA open when you paid for LASIK, you can reimburse yourself at any point in the future. There is no deadline." } ] }, "calculation": { "inputs": { "typicalCost": 5000, "taxRate": "33%", "years": 5, "annualReturn": "7%" }, "results": { "futureValue": 7013, "investmentGrowth": 2013, "taxSavings": 1665, "totalBenefit": 3678 } } }, "meta": { "source": "https://www.hsatrackr.com/compare/hsa-vs-cash/lasik", "citation_url": "https://www.hsatrackr.com/compare/hsa-vs-cash/lasik", "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" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/calculator/form-8889": { "get": { "tags": [ "Calculators" ], "summary": "Form 8889 Deduction Calculator", "description": "Calculate HSA deduction amounts for IRS Form 8889 filing based on coverage type and contributions.", "operationId": "calculateForm8889", "parameters": [ { "name": "coverage", "in": "query", "description": "Coverage type. Defaults to self.", "required": false, "schema": { "type": "string", "enum": [ "self", "family" ], "example": "family", "default": "self" } }, { "name": "age55", "in": "query", "description": "Whether account holder is 55 or older (for catch-up contributions)", "required": false, "schema": { "type": "boolean", "example": false, "default": false } }, { "name": "directContributions", "in": "query", "description": "Direct contributions amount in USD", "required": false, "schema": { "type": "number", "example": 4400, "default": 4400 } }, { "name": "employerContributions", "in": "query", "description": "Employer contributions amount in USD (optional)", "required": false, "schema": { "type": "number", "example": 2000, "default": 0 } }, { "name": "age65", "in": "query", "required": false, "description": "Account holder was 65 or older (Line 17b penalty exception)", "schema": { "type": "boolean", "default": false } }, { "name": "totalDistributions", "in": "query", "required": false, "description": "Total HSA distributions in the year (Form 1099-SA box 1)", "schema": { "type": "number", "default": 0, "minimum": 0 } }, { "name": "qualifiedExpenses", "in": "query", "required": false, "description": "Unreimbursed qualified medical expenses paid from distributions", "schema": { "type": "number", "default": 0, "minimum": 0 } }, { "name": "rollovers", "in": "query", "required": false, "description": "Distributions rolled over or transferred to another HSA", "schema": { "type": "number", "default": 0, "minimum": 0 } }, { "name": "year", "in": "query", "required": false, "description": "Tax year; must have published IRS limits", "schema": { "type": "integer", "default": 2026 } } ], "responses": { "200": { "description": "Form 8889 deduction calculation", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "inputs": { "type": "object", "properties": { "year": { "type": "integer" }, "coverage": { "type": "string" }, "age55Plus": { "type": "boolean" }, "age65Plus": { "type": "boolean" }, "directContributions": { "type": "integer" }, "employerContributions": { "type": "integer" }, "totalDistributions": { "type": "integer" }, "qualifiedExpenses": { "type": "integer" }, "rollovers": { "type": "integer" } }, "required": [ "year", "coverage", "age55Plus", "age65Plus", "directContributions", "employerContributions", "totalDistributions", "qualifiedExpenses", "rollovers" ] }, "limits": { "type": "object", "properties": { "selfOnly": { "type": "integer" }, "family": { "type": "integer" }, "catchUp": { "type": "integer" } }, "required": [ "selfOnly", "family", "catchUp" ] }, "results": { "type": "object", "properties": { "annualLimit": { "type": "integer" }, "catchUp": { "type": "integer" }, "maxContribution": { "type": "integer" }, "totalContributions": { "type": "integer" }, "deductibleAmount": { "type": "integer" }, "excessContribution": { "type": "integer" }, "taxableDistributions": { "type": "integer" }, "penaltyAmount": { "type": "integer" } }, "required": [ "annualLimit", "catchUp", "maxContribution", "totalContributions", "deductibleAmount", "excessContribution", "taxableDistributions", "penaltyAmount" ] } }, "required": [ "inputs", "limits", "results" ], "description": "result" }, "meta": { "$ref": "#/components/schemas/MetaInfo" } } }, "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "schemas": { "MetaInfo": { "type": "object", "description": "Metadata included with every API response", "properties": { "source": { "type": "string", "description": "Data source (IRS publications, provider websites, etc.)" }, "citation_url": { "type": "string", "format": "uri", "description": "Canonical public URL to cite for this response" }, "updated": { "type": "string", "format": "date", "description": "Date this API build was published (YYYY-MM-DD). Examples in the docs are pinned to 2026-01-01" }, "disclaimer": { "type": "string", "description": "Legal disclaimer" }, "api_docs": { "type": "string", "description": "Link to API documentation" } }, "required": [ "source", "citation_url", "updated", "disclaimer", "api_docs" ] }, "EligibleExpense": { "type": "object", "description": "One canonical HSA eligibility ruling. The same shape is returned by the list and detail endpoints.", "required": [ "slug", "name", "category", "eligibility", "description", "details", "requirements", "commonCost", "faqs", "relatedSlugs" ], "properties": { "slug": { "type": "string", "example": "sunscreen" }, "name": { "type": "string", "example": "Sunscreen" }, "category": { "type": "string", "enum": [ "medical", "dental", "vision", "pharmacy", "mental-health", "lab-tests", "preventive-care", "equipment-supplies" ] }, "eligibility": { "type": "string", "enum": [ "eligible", "partially", "ineligible" ], "description": "partially = eligible only with conditions (see requirements and conditionalEvidenceTypes)" }, "description": { "type": "string" }, "details": { "type": "string" }, "requirements": { "type": "string", "nullable": true, "description": "Conditions for partially eligible items, or null" }, "conditionalEvidenceTypes": { "type": "array", "items": { "type": "string", "enum": [ "prescription", "letter_of_medical_necessity", "physician_order", "medical_necessity_statement", "service_animal_documentation", "care_plan", "policy_or_coverage_document", "treatment_and_legal_records", "appointment_records", "medical_cost_allocation", "membership_agreement" ] }, "description": "Proof to keep for partially eligible items" }, "commonCost": { "type": "string", "example": "$8-$30 per bottle" }, "faqs": { "type": "array", "items": { "type": "object", "required": [ "question", "answer" ], "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } }, "relatedSlugs": { "type": "array", "items": { "type": "string" } }, "seoTitle": { "type": "string" }, "seoDescription": { "type": "string" }, "sourceBasis": { "type": "array", "description": "Primary sources behind the ruling. Missing when not yet sourced.", "items": { "$ref": "#/components/schemas/SourceBasis" } }, "benefitCallout": { "type": "object", "required": [ "taxSavingsExample" ], "properties": { "taxSavingsExample": { "type": "string" }, "strategyTip": { "type": "string" }, "pillarLink": { "type": "string" } } } } }, "EligibleExpenseDetail": { "allOf": [ { "$ref": "#/components/schemas/EligibleExpense" } ] }, "GlossaryTerm": { "type": "object", "description": "Summary of a glossary term", "properties": { "slug": { "type": "string" }, "term": { "type": "string" }, "category": { "type": "string", "enum": [ "accounts", "plans", "contributions", "expenses", "taxes", "strategies", "providers", "other" ] }, "definition": { "type": "string" }, "relatedTerms": { "type": "array", "items": { "type": "string" } } }, "required": [ "slug", "term", "category", "definition" ] }, "GlossaryTermDetail": { "type": "object", "description": "Detailed glossary term with expanded explanation", "allOf": [ { "$ref": "#/components/schemas/GlossaryTerm" }, { "type": "object", "properties": { "expandedExplanation": { "type": "string" }, "examples": { "type": "array", "items": { "type": "string" } }, "relatedTerms": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "term": { "type": "string" } } } } } } ] }, "Provider": { "type": "object", "description": "Summary of an HSA custodian provider", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "fees": { "type": "object", "properties": { "accountMaintenance": { "type": "number" }, "investmentFees": { "type": "string" } } }, "investmentOptions": { "type": "array", "items": { "type": "string" } }, "highlights": { "type": "array", "items": { "type": "string" } } }, "required": [ "slug", "name", "website" ] }, "ProviderDetail": { "type": "object", "description": "Detailed provider information", "allOf": [ { "$ref": "#/components/schemas/Provider" }, { "type": "object", "properties": { "description": { "type": "string" }, "debitCard": { "type": "boolean" }, "mobileApp": { "type": "boolean" } } } ] }, "StateGuide": { "type": "object", "description": "State-specific HSA tax information", "properties": { "slug": { "type": "string" }, "state": { "type": "string" }, "taxTreatment": { "type": "string", "description": "How the state treats HSA contributions (Deductible, Excluded, etc.)" }, "summary": { "type": "string" }, "highlights": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } }, "required": [ "slug", "state", "taxTreatment", "summary" ] }, "SourceBasis": { "type": "object", "required": [ "label", "url", "supports", "reviewedDate" ], "properties": { "label": { "type": "string", "example": "IRS Publication 502" }, "url": { "type": "string", "format": "uri" }, "supports": { "type": "string", "description": "What this source supports in the ruling" }, "reviewedDate": { "type": "string", "format": "date" } } }, "EligibilityCheckItem": { "type": "object", "properties": { "slug": { "type": "string", "description": "Use with /api/v1/eligible/{slug}" }, "name": { "type": "string", "description": "Display name" }, "category": { "type": "string", "description": "Expense category" }, "eligibility": { "type": "string", "enum": [ "eligible", "partially", "ineligible" ], "description": "eligible, partially (only with conditions, see requirements) or ineligible" }, "description": { "type": "string", "description": "One-sentence ruling" }, "requirements": { "type": "string", "nullable": true, "description": "Conditions for a partially eligible item, else null" }, "sourceBasis": { "type": "array", "items": { "$ref": "#/components/schemas/SourceBasis" }, "description": "Linked sources behind the ruling; empty when none are linked yet" }, "url": { "type": "string", "format": "uri", "description": "Public page that explains the ruling. Link it when you show the answer" } }, "required": [ "slug", "name", "category", "eligibility", "description", "requirements", "sourceBasis", "url" ] }, "Error": { "type": "object", "description": "Body of every 400 and 404 response", "required": [ "error", "meta" ], "properties": { "error": { "type": "string", "description": "What went wrong, naming the parameter or slug" }, "meta": { "type": "object", "required": [ "disclaimer", "api_docs" ], "properties": { "disclaimer": { "type": "string" }, "api_docs": { "type": "string", "format": "uri" } } } } } }, "responses": { "BadRequest": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Query parameter q is required (2+ characters)", "meta": { "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" } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Expense \"not-a-real-slug\" not found", "meta": { "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" } } } } }, "TooManyRequests": { "description": "Rate limit exceeded (30 requests per minute per IP)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "example": { "error": "Too many requests. Please try again later." } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until you can retry" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time in milliseconds when the window resets" } } } } } }