---
title: "Estimate U.S. federal income tax"
method: POST
path: "/v1/tax/estimate"
tags: ["Tax"]
---

# Estimate U.S. federal income tax

`POST /v1/tax/estimate`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/tax/estimate`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Estimates federal income tax for planning purposes: ordinary-income brackets, the standard deduction (with optional itemized override), long-term capital gains / qualified dividends stacked on top of ordinary income, the 3.8% Net Investment Income Tax, the 0.9% Additional Medicare Tax on earned income, and an optional flat state rate. Calculation engine output, not tax advice — credits, AMT, phase-outs, QBI, and state-specific rules beyond a flat rate are not modeled. Deterministic.

## Request body

- TaxEstimateRequest
  - `tax_year` integer, required: Supported: 2025, 2026.
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required: single, married filing jointly (mfj), married filing separately (mfs), head of household (hoh).
  - `ordinary_income` number: Income taxed at ordinary rates: wages, interest, non-qualified dividends, taxable retirement distributions, short-term gains.
  - `qualified_income` number: Long-term capital gains plus qualified dividends, taxed at preferential rates.
  - `itemized_deductions` number: If greater than the standard deduction, used in its place.
  - `net_investment_income` number: Basis for the 3.8% NIIT. Defaults to qualified_income if omitted.
  - `wages` number: Earned income subject to the 0.9% Additional Medicare Tax. Not added to income; only sets the surtax basis.
  - `state_tax_rate` number: Flat state income-tax rate applied to AGI (an approximation; ignored when `state` is set).
  - `state` string: Optional 2-letter state code or DC. Computes the real per-state tax (all 50 states + DC, 2025) instead of state_tax_rate, and adds combined figures.
  - `state_taxable_income` number: State taxable income (non-SS) before the state standard deduction; defaults to ordinary_income.
  - `social_security_income` number: Social Security income; taxed only by the 9 states that tax SS (with `state` set).
  - `include_amt` boolean: Compute the Alternative Minimum Tax (§55) and fold any AMT owed into total_tax. Off by default.
  - `amt_preference_items` number: Sum of AMT add-backs to AMTI: SALT deducted for regular tax, the ISO bargain element, private-activity-bond interest, etc. Used only when include_amt is set.
  - `include_qbi` boolean: Compute the §199A Qualified Business Income deduction and reduce taxable income by it. Off by default.
  - `qbi` number: Net qualified business income from pass-through trades/businesses. Used only when include_qbi is set.
  - `qbi_w2_wages` number: W-2 wages paid by the business; basis for the wage/UBIA limit that phases in above the threshold (greater of 50% of wages, or 25% of wages + 2.5% of UBIA).
  - `qbi_ubia` number: Unadjusted basis immediately after acquisition (UBIA) of qualified property; the second term of the wage/UBIA limit.
  - `qbi_is_sstb` boolean: Specified service trade or business (health, law, consulting, etc.); the deduction phases out entirely above the range.
  - `qbi_reit_ptp_dividends` number: Qualified REIT dividends + publicly-traded-partnership income; deductible at 20% with no wage/UBIA limit and no SSTB restriction.
  - `include_credits` boolean: Compute the §24 Child Tax Credit and §32 Earned Income Credit and fold them into total_tax (which may go negative — a net refund). Off by default. Eligibility (EITC age/residency/joint-filing rules) is the caller's responsibility.
  - `qualifying_children` integer: Number of children qualifying for the Child Tax Credit (under 17). Used only when include_credits is set.
  - `other_dependents` integer: Number of dependents qualifying for the $500 (nonrefundable) Credit for Other Dependents.
  - `eitc_qualifying_children` integer: Number of children under the EITC definition (broader than the CTC's — through age 18, or 23 if a student). Capped at 3 for the credit table. Earned income is approximated by wages.
  - `aged_blind_count` integer: Number of §63(f) additional-standard-deduction conditions: count 1 for each of the taxpayer/spouse who is 65+ and each who is blind (0–4). Increases the standard deduction only ($2,000 unmarried / $1,600 married in 2025); ignored when itemizing.
  - `include_itemized_limit` boolean: Apply the §68 overall limitation on itemized deductions (OBBBA's 2/37 reduction, in force for 2026+; suspended in 2025). Off by default; only changes a 37%-bracket itemizer.
  - `salt_paid` number: State-and-local taxes included in itemized_deductions, used to apply the §164(b)(6) cap ($40,000 in 2025 / $40,400 in 2026, phasing down 30% above $500k/$505k MAGI to a $10,000 floor). itemized_deductions should be the gross total including the full uncapped SALT. Must not exceed itemized_deductions.
  - `charitable_contributions` number: Charitable-giving portion included in itemized_deductions, used to apply the OBBBA §170(b)(1)(I) 0.5%-of-AGI floor for tax years 2026+: the deduction is reduced by min(charitable, 0.5% × AGI), since only giving above 0.5% of AGI is deductible. Assumed to already respect the §170(b) percentage ceilings (60/30/20% of AGI) — a lump-sum total can't separate cash vs noncash gifts — and carryforward of floored amounts is not modeled. Must not exceed itemized_deductions; no effect before 2026.
  - `force_itemize` boolean: Disable the standard-deduction floor so the deduction equals itemized_deductions even when below the standard. Models §63(c)(6)(A): a married-filing-separately taxpayer whose spouse itemizes may not take the standard deduction. Off by default (deduction = max(standard, itemized)).
  - `senior_count` integer: Number of taxpayers age 65+ claiming the §151(d)(5) senior deduction (OBBBA, 2025–2028); 2 only on a joint return. Adds $6,000 each on top of the standard/itemized deduction, phasing out 6% of MAGI above $75,000 ($150,000 MFJ). Not available to MFS.
  - `retirement_contributions` number: IRA/401(k)/etc. contributions eligible for the §25B Saver's Credit (used only with include_credits). Counted up to $2,000 per person ($4,000 MFJ); the nonrefundable credit is 50/20/10% of that by AGI bracket. Eligibility (not a full-time student or dependent, age 18+) is the caller's responsibility.
  - `aotc_student_expenses` number[]: §25A American Opportunity Credit: per-student qualified education expenses (one entry per student). Each yields 100% of the first $2,000 + 25% of the next $2,000 (max $2,500); 40% of the total is refundable. Shares the §25A MAGI phase-out ($80k–$90k single / $160k–$180k MFJ); not available to MFS. Used only with include_credits.
  - `llc_expenses` number: §25A Lifetime Learning Credit: total qualified expenses (20% of up to $10,000 = max $2,000 per return, nonrefundable; same phase-out as the AOTC).
  - `dependent_care_expenses` number: §21 child- and dependent-care expenses. Applied at the applicable percentage (35%→20% by AGI in 2025; the OBBBA two-stage 50%→35%→20% in 2026), capped at $3,000 (1 qualifying individual) / $6,000 (2+). Nonrefundable; the earned-income limit is the caller's responsibility.
  - `dependent_care_count` integer: Number of qualifying individuals for the §21 dependent-care credit (sets the $3,000 vs $6,000 expense cap).
  - `adoption_expenses` number: §23 qualified adoption expenses (capped at $17,280 in 2025 / $17,670 in 2026). The credit phases out over $40k of MAGI above $259,190/$265,080; the OBBBA refundable portion (up to $5,000/$5,120) is paid even with no tax liability.
  - `adoption_special_needs` boolean: If true, the §23 credit is the full year maximum regardless of actual expenses (adoption of a child with special needs).

## Response `200`

Tax estimate

- TaxEstimateResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` TaxEstimateRequest
    - `tax_year` integer, required: Supported: 2025, 2026.
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required: single, married filing jointly (mfj), married filing separately (mfs), head of household (hoh).
    - `ordinary_income` number: Income taxed at ordinary rates: wages, interest, non-qualified dividends, taxable retirement distributions, short-term gains.
    - `qualified_income` number: Long-term capital gains plus qualified dividends, taxed at preferential rates.
    - `itemized_deductions` number: If greater than the standard deduction, used in its place.
    - `net_investment_income` number: Basis for the 3.8% NIIT. Defaults to qualified_income if omitted.
    - `wages` number: Earned income subject to the 0.9% Additional Medicare Tax. Not added to income; only sets the surtax basis.
    - `state_tax_rate` number: Flat state income-tax rate applied to AGI (an approximation; ignored when `state` is set).
    - `state` string: Optional 2-letter state code or DC. Computes the real per-state tax (all 50 states + DC, 2025) instead of state_tax_rate, and adds combined figures.
    - `state_taxable_income` number: State taxable income (non-SS) before the state standard deduction; defaults to ordinary_income.
    - `social_security_income` number: Social Security income; taxed only by the 9 states that tax SS (with `state` set).
    - `include_amt` boolean: Compute the Alternative Minimum Tax (§55) and fold any AMT owed into total_tax. Off by default.
    - `amt_preference_items` number: Sum of AMT add-backs to AMTI: SALT deducted for regular tax, the ISO bargain element, private-activity-bond interest, etc. Used only when include_amt is set.
    - `include_qbi` boolean: Compute the §199A Qualified Business Income deduction and reduce taxable income by it. Off by default.
    - `qbi` number: Net qualified business income from pass-through trades/businesses. Used only when include_qbi is set.
    - `qbi_w2_wages` number: W-2 wages paid by the business; basis for the wage/UBIA limit that phases in above the threshold (greater of 50% of wages, or 25% of wages + 2.5% of UBIA).
    - `qbi_ubia` number: Unadjusted basis immediately after acquisition (UBIA) of qualified property; the second term of the wage/UBIA limit.
    - `qbi_is_sstb` boolean: Specified service trade or business (health, law, consulting, etc.); the deduction phases out entirely above the range.
    - `qbi_reit_ptp_dividends` number: Qualified REIT dividends + publicly-traded-partnership income; deductible at 20% with no wage/UBIA limit and no SSTB restriction.
    - `include_credits` boolean: Compute the §24 Child Tax Credit and §32 Earned Income Credit and fold them into total_tax (which may go negative — a net refund). Off by default. Eligibility (EITC age/residency/joint-filing rules) is the caller's responsibility.
    - `qualifying_children` integer: Number of children qualifying for the Child Tax Credit (under 17). Used only when include_credits is set.
    - `other_dependents` integer: Number of dependents qualifying for the $500 (nonrefundable) Credit for Other Dependents.
    - `eitc_qualifying_children` integer: Number of children under the EITC definition (broader than the CTC's — through age 18, or 23 if a student). Capped at 3 for the credit table. Earned income is approximated by wages.
    - `aged_blind_count` integer: Number of §63(f) additional-standard-deduction conditions: count 1 for each of the taxpayer/spouse who is 65+ and each who is blind (0–4). Increases the standard deduction only ($2,000 unmarried / $1,600 married in 2025); ignored when itemizing.
    - `include_itemized_limit` boolean: Apply the §68 overall limitation on itemized deductions (OBBBA's 2/37 reduction, in force for 2026+; suspended in 2025). Off by default; only changes a 37%-bracket itemizer.
    - `salt_paid` number: State-and-local taxes included in itemized_deductions, used to apply the §164(b)(6) cap ($40,000 in 2025 / $40,400 in 2026, phasing down 30% above $500k/$505k MAGI to a $10,000 floor). itemized_deductions should be the gross total including the full uncapped SALT. Must not exceed itemized_deductions.
    - `charitable_contributions` number: Charitable-giving portion included in itemized_deductions, used to apply the OBBBA §170(b)(1)(I) 0.5%-of-AGI floor for tax years 2026+: the deduction is reduced by min(charitable, 0.5% × AGI), since only giving above 0.5% of AGI is deductible. Assumed to already respect the §170(b) percentage ceilings (60/30/20% of AGI) — a lump-sum total can't separate cash vs noncash gifts — and carryforward of floored amounts is not modeled. Must not exceed itemized_deductions; no effect before 2026.
    - `force_itemize` boolean: Disable the standard-deduction floor so the deduction equals itemized_deductions even when below the standard. Models §63(c)(6)(A): a married-filing-separately taxpayer whose spouse itemizes may not take the standard deduction. Off by default (deduction = max(standard, itemized)).
    - `senior_count` integer: Number of taxpayers age 65+ claiming the §151(d)(5) senior deduction (OBBBA, 2025–2028); 2 only on a joint return. Adds $6,000 each on top of the standard/itemized deduction, phasing out 6% of MAGI above $75,000 ($150,000 MFJ). Not available to MFS.
    - `retirement_contributions` number: IRA/401(k)/etc. contributions eligible for the §25B Saver's Credit (used only with include_credits). Counted up to $2,000 per person ($4,000 MFJ); the nonrefundable credit is 50/20/10% of that by AGI bracket. Eligibility (not a full-time student or dependent, age 18+) is the caller's responsibility.
    - `aotc_student_expenses` number[]: §25A American Opportunity Credit: per-student qualified education expenses (one entry per student). Each yields 100% of the first $2,000 + 25% of the next $2,000 (max $2,500); 40% of the total is refundable. Shares the §25A MAGI phase-out ($80k–$90k single / $160k–$180k MFJ); not available to MFS. Used only with include_credits.
    - `llc_expenses` number: §25A Lifetime Learning Credit: total qualified expenses (20% of up to $10,000 = max $2,000 per return, nonrefundable; same phase-out as the AOTC).
    - `dependent_care_expenses` number: §21 child- and dependent-care expenses. Applied at the applicable percentage (35%→20% by AGI in 2025; the OBBBA two-stage 50%→35%→20% in 2026), capped at $3,000 (1 qualifying individual) / $6,000 (2+). Nonrefundable; the earned-income limit is the caller's responsibility.
    - `dependent_care_count` integer: Number of qualifying individuals for the §21 dependent-care credit (sets the $3,000 vs $6,000 expense cap).
    - `adoption_expenses` number: §23 qualified adoption expenses (capped at $17,280 in 2025 / $17,670 in 2026). The credit phases out over $40k of MAGI above $259,190/$265,080; the OBBBA refundable portion (up to $5,000/$5,120) is paid even with no tax liability.
    - `adoption_special_needs` boolean: If true, the §23 credit is the full year maximum regardless of actual expenses (adoption of a child with special needs).
  - `result` object
    - `agi` number: Adjusted gross income (ordinary + qualified).
    - `deduction_used` number
    - `taxable_income` number
    - `ordinary_tax` number: Tax on the ordinary-rate portion.
    - `capital_gains_tax` number: Tax on LTCG / qualified dividends.
    - `federal_income_tax` number: ordinary_tax + capital_gains_tax.
    - `niit` number: 3.8% Net Investment Income Tax.
    - `additional_medicare_tax` number: 0.9% Additional Medicare Tax.
    - `state_tax` number: Flat-rate state tax, or the real per-state tax when `state` is set.
    - `total_tax` number: Federal + state.
    - `marginal_ordinary_rate` number: Rate on the next ordinary dollar.
    - `effective_rate` number: total_tax / agi.
    - `state_name` string: Present when `state` is set.
    - `state_marginal_rate` number: State rate on the next dollar (present when `state` is set).
    - `combined_marginal_rate` number: Federal ordinary + state marginal (present when `state` is set).
    - `amt_income` number: Alternative Minimum Taxable Income (present when include_amt is set).
    - `amt_exemption` number: AMT exemption after phase-out (present when include_amt is set).
    - `tentative_minimum_tax` number: Tentative minimum tax (present when include_amt is set).
    - `amt` number: AMT owed above the regular tax; already included in total_tax (present when include_amt is set and positive).
    - `qbi_deduction` number: §199A QBI deduction; already reflected in taxable_income and the tax figures (present when include_qbi is set and positive).
    - `itemized_deduction_reduction` number: §68 reduction of itemized deductions; already reflected in taxable_income and the tax figures (present when include_itemized_limit applies and positive).
    - `salt_reduction` number: §164(b)(6) disallowed SALT; already reflected in taxable_income and the tax figures (present when salt_paid is set and the cap binds).
    - `charity_floor_reduction` number: §170(b)(1)(I) 0.5%-of-AGI charitable giving disallowed (2026+); already reflected in taxable_income (present when charitable_contributions is set).
    - `senior_deduction` number: §151(d)(5) senior deduction applied; already reflected in taxable_income and the tax figures (present when senior_count is set and positive).
    - `child_tax_credit` number: §24 Child Tax Credit, nonrefundable portion applied to tax (present when include_credits is set and positive).
    - `additional_child_tax_credit` number: §24(d) refundable Additional Child Tax Credit (present when include_credits is set and positive).
    - `earned_income_credit` number: §32 Earned Income Credit, refundable (present when include_credits is set and positive).
    - `savers_credit` number: §25B Saver's Credit, nonrefundable (present when include_credits is set and positive).
    - `education_credit` number: §25A education credit realized (AOTC, incl. its 40% refundable portion, + LLC); present when include_credits is set and positive.
    - `dependent_care_credit` number: §21 child- and dependent-care credit, nonrefundable (present when include_credits is set and positive).
    - `adoption_credit` number: §23 adoption credit realized (nonrefundable + refundable portions); present when include_credits is set and positive.
    - `total_credits` number: Total credit actually applied (nonrefundable credits capped at tax liability + all refundable parts); already reflected in total_tax (present when include_credits is set and positive).
  - `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)