Tax

Estimate U.S. federal income tax

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.

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

Request body

tax_yearinteger 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_incomenumber

Income taxed at ordinary rates: wages, interest, non-qualified dividends, taxable retirement distributions, short-term gains.

qualified_incomenumber

Long-term capital gains plus qualified dividends, taxed at preferential rates.

itemized_deductionsnumber

If greater than the standard deduction, used in its place.

net_investment_incomenumber

Basis for the 3.8% NIIT. Defaults to qualified_income if omitted.

wagesnumber

Earned income subject to the 0.9% Additional Medicare Tax. Not added to income; only sets the surtax basis.

state_tax_ratenumber

Flat state income-tax rate applied to AGI (an approximation; ignored when state is set).

statestring

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_incomenumber

State taxable income (non-SS) before the state standard deduction; defaults to ordinary_income.

social_security_incomenumber

Social Security income; taxed only by the 9 states that tax SS (with state set).

include_amtboolean

Compute the Alternative Minimum Tax (§55) and fold any AMT owed into total_tax. Off by default.

amt_preference_itemsnumber

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_qbiboolean

Compute the §199A Qualified Business Income deduction and reduce taxable income by it. Off by default.

qbinumber

Net qualified business income from pass-through trades/businesses. Used only when include_qbi is set.

qbi_w2_wagesnumber

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_ubianumber

Unadjusted basis immediately after acquisition (UBIA) of qualified property; the second term of the wage/UBIA limit.

qbi_is_sstbboolean

Specified service trade or business (health, law, consulting, etc.); the deduction phases out entirely above the range.

qbi_reit_ptp_dividendsnumber

Qualified REIT dividends + publicly-traded-partnership income; deductible at 20% with no wage/UBIA limit and no SSTB restriction.

include_creditsboolean

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_childreninteger

Number of children qualifying for the Child Tax Credit (under 17). Used only when include_credits is set.

other_dependentsinteger

Number of dependents qualifying for the $500 (nonrefundable) Credit for Other Dependents.

eitc_qualifying_childreninteger

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_countinteger

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_limitboolean

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_paidnumber

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_contributionsnumber

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_itemizeboolean

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_countinteger

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_contributionsnumber

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_expensesnumber[]

§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_expensesnumber

§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_expensesnumber

§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_countinteger

Number of qualifying individuals for the §21 dependent-care credit (sets the $3,000 vs $6,000 expense cap).

adoption_expensesnumber

§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_needsboolean

If true, the §23 credit is the full year maximum regardless of actual expenses (adoption of a child with special needs).

Example request

{
  "tax_year": 2026,
  "state": "CA"
}

Response

Tax estimate

result_idstring
engine_versionstring
disclaimerstring

Example response

{
  "result_id": "tax_1a2b3c4d5e6f7a8b",
  "engine_version": "tax-1.0.0",
  "inputs": {
    "tax_year": 2026,
    "state": "CA"
  },
  "result": {
    "marginal_ordinary_rate": 0.22
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.