State tax docs / API reference

State income tax API reference

One HTTP call returns a year of state income tax for any of the 50 states or the District of Columbia, the rules that produced it, and the official source of each of those rules. The engine behind it is documented rule by rule, with sources, under State tax engine documentation. Engine version 1.14.2, tax year 2026.

Endpoints: POST /api/state-tax (licensed) computes a return; GET /api/state-tax/states, /rules and /schema (public) describe the jurisdictions, each one's rule set and the request and response formats. Evaluation says how to try it.

Request

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "AL",
  "filingStatus": "mfj",
  "age": 67,
  "iraDistributions": 30000,
  "pensionPublic": 24000,
  "socialSecurity": 28000,
  "socialSecurityGross": 36000,
  "capitalGains": 5000,
  "spouse": {
    "age": 64,
    "iraDistributions": 12000
  }
}

Field	Type	Required	When absent	Meaning	Component or part of another amount	Limits and errors
`state` also `state_code`	string	yes	(none: 400)	Two-letter code, or DC (case-insensitive). How it is read.	Required; not an amount.	One of the 50 state codes or DC, any case (the sentinel NONE, no state tax, is also accepted). Absent, empty or not a string: 400 "state is required"; any other value: 400 "state is not one we carry".
`filingStatus` also `filing_status`	string	no	single	single, mfj or married_filing_jointly, mfs or married_filing_separately, hoh or head_of_household, qss or qualifying_surviving_spouse (case-insensitive). A qualifying surviving spouse is one person on the return (no spouse object) and gets the state's own treatment of the status: the joint schedule, deduction or limits, the head-of-household return, or the single return, as each state page says. Anything else, including a non-string, is refused with 400. How it is read.	Not an amount.	One of the nine strings, any case; null = absent. Anything else: 400 naming the field.
`age`	integer	no	0	The primary filer's age, a whole number from 0 to 120. A non-number or a fraction is refused with 400 (engine 1.5.0). How it is read.	The primary filer's age (the household's without spouse). Every age test reads it.	Whole number 0 to 120; null = absent (0). A fraction or non-number: 400.
`ordinaryIncome` also `ordinary_income`	number	no	0	Ordinary income not in another field: interest, non-qualified dividends and so on. Not negative. A non-number is refused with 400 (engine 1.5.0). How it is read.	Component: a separate amount, added to income once. Does not contain wages, qualifiedDividends, shortTermGains or any retirement field.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`qualifiedDividends` also `qualified_dividends`	number	no	not supplied (none)	Qualified dividends, in addition to ordinaryIncome (do not count them twice). Ordinary income except where the state treats them apart (North Dakota's exclusion; Georgia's and Delaware's retirement pools). How it is read.	Component, disjoint from ordinaryIncome: add it, do not include it there too.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`capitalLoss` also `capital_loss`	number	no	not supplied (none)	The year's net capital loss as a positive amount: capital losses in excess of capital gains (federal Schedule D line 16), including any carryover brought into the year. What the state deducts is its own rule: the federal $3,000 ($1,500 married filing separately) where it follows the federal return, Massachusetts $2,000 against interest and dividends only, Alabama the whole in-year loss, Pennsylvania and New Jersey nothing. How it is read.	A net loss excludes a net gain: capitalGains and shortTermGains must be 0 with it; a household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field; 400 with capitalGains or shortTermGains above 0.
`capitalLossCarryover` also `capital_loss_carryover`	number	no	not supplied (none)	The part of capitalLoss carried into the year from earlier years (Schedule D lines 6 and 14). Only Alabama reads it (no carryover there: it deducts the rest). Where a state keeps its own carryover (Massachusetts, Wisconsin) give that state's figure in both fields. How it is read.	A part of capitalLoss.	Finite, from 0 to $100 billion, at most capitalLoss; null = absent. Otherwise 400 naming the field.
`wages`	number	no	not supplied	Earned income: W-2 wages and, without computeFederal, net self-employment income as it reaches federal AGI (the net profit less the deduction for half the self-employment tax). With computeFederal it is the person's W-2 wages only (one employer: boxes 1, 3 and 5 alike) and a business's net profit goes in selfEmploymentIncome. How it is read.	Component. With spouse: the primary filer's own amount (spouse.wages is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`selfEmploymentIncome` also `self_employment_income`	number	no	not supplied (none)	Net profit from self-employment (Schedule C line 31, or a partner's Schedule K-1 box 14 code A), at least 0. Needs computeFederal: true. The federal engine prices it on the person's Schedule SE and Schedule 1, and the state engine receives it as earned income less half the person's self-employment tax (the business income as it reaches federal AGI), together with the person's wages. Without computeFederal an amount other than 0 is refused with 400: send the state earned income as wages instead. How it is read.	Component, disjoint from wages. With spouse: the primary filer's own amount (spouse.selfEmploymentIncome is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Not 0 without computeFederal: true, else 400.
`iraDistributions` also `ira_distributions`	number	no	not supplied	Traditional IRA distributions, excluding conversions. 401(k), 403(b) and 457(b) distributions go in employerPlanDistributions. How it is read.	Component, disjoint from employerPlanDistributions and rothConversion. With spouse: the primary filer's own amount (spouse.iraDistributions is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`employerPlanDistributions` also `employer_plan_distributions`	number	no	not supplied	401(k), 403(b) and 457(b) distributions, excluding conversions. Taxed like IRA distributions except where the state's pension rule covers employer plans (Maryland, Rhode Island). How it is read.	Component, disjoint from iraDistributions. With spouse: the primary filer's own amount (spouse.employerPlanDistributions is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`pensionPrivate` also `pension_private`	number	no	not supplied	Private-employer pension or annuity. How it is read.	Component, disjoint from disabilityIncome. With spouse: the primary filer's own amount (spouse.pensionPrivate is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`pensionPublic` also `pension_public`	number	no	not supplied	Government or public-employer pension. How it is read.	Component, disjoint from pensionFederalCivilService and pensionMilitary. With spouse: the primary filer's own amount (spouse.pensionPublic is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`pensionMilitary` also `pension_military`	number	no	not supplied	Military retirement pay. How it is read.	Component. With spouse: the primary filer's own amount (spouse.pensionMilitary is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`rothConversion` also `roth_conversion`	number	no	not supplied	Traditional-to-Roth conversion amount. How it is read.	Component, not part of iraDistributions. With spouse: the primary filer's own amount (spouse.rothConversion is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`shortTermGains` also `short_term_gains`	number	no	not supplied	Net short-term capital gain. How it is read.	Component; a household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`capitalGains` also `capital_gains`	number	no	0	Net long-term capital gain. Not negative. A non-number is refused with 400 (engine 1.5.0). How it is read.	Component; a household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`socialSecurity` also `social_security`	number	no	0	The federally taxable part of Social Security benefits, not gross benefits. Not negative. A non-number is refused with 400 (engine 1.5.0). How it is read.	Component (the taxable part); a household total. It is part of socialSecurityGross.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`socialSecurityGross` also `social_security_gross`	number	no	not supplied (the engine estimates where a rule needs it)	Gross benefits (Social Security and Railroad Retirement Tier 1 received), for the rules that run on gross benefits. At least socialSecurity. How it is read.	Contains socialSecurity (and railroadRetirementTier1); a household total. Not added to income: the rules that run on gross benefits read it.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. When given and above 0, at least socialSecurity, else 400.
`railroadRetirementTier1` also `railroad_retirement_tier1`	number	no	not supplied (none)	The Railroad Retirement Tier 1 part of socialSecurityGross (needs it, at most it). Its share of the taxable benefits is kept out of every state's Social Security rules. How it is read.	Part of socialSecurityGross; a household total even with spouse (spouse.railroadRetirementTier1 is the spouse's part of it). Not added to income again.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Needs socialSecurityGross and at most it, else 400.
`railroadRetirementTier2` also `railroad_retirement_tier2`	number	no	not supplied (none)	Railroad Retirement Tier 2 and supplemental annuities (the taxable amount on RRB-1099-R). Never taxed by a state; counted in the income tests and, where the state says so, against a retirement cap. How it is read.	Component. With spouse: the primary filer's own amount (spouse.railroadRetirementTier2 is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`federalTax` also `federal_tax`	number	no	not supplied (no federal-tax deduction)	The year's federal income tax after the nonrefundable credits (Form 1040 line 22), without the net investment income tax (that goes in federalNiit) or the other Schedule 2 taxes. Read by five states: Alabama deducts it with federalNiit, less federalRefundableCredits (its worksheet subtracts the refundable credits); Missouri deducts a percentage of it and Oregon deducts it up to its cap; Nebraska caps its tax at the federal tax before credits and Oklahoma's child credit is limited by it, so those two read federalTaxBeforeCredits when it is given (without it Nebraska takes no cap, and Oklahoma reads a positive federalTax as the whole nonrefundable credit allowed and 0 as none of it). Every other state ignores it. How it is read.	Not income: a federal figure some states deduct or compare with; a household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. With federalTaxBeforeCredits, at most that figure (else 400).
`federalNiit` also `federal_niit`	number	no	not supplied	The year's federal net investment income tax. How it is read.	Not income: read with federalTax.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`federalTaxBeforeCredits` also `federal_tax_before_credits`	number	no	not supplied (NE: no federal-tax cap when only federalTax is given; OK: the nonrefundable child credit limit is read from federalTax)	The year's federal tax before credits (Form 1040 line 16 plus Schedule 2 lines 2 and 8), which Nebraska caps its tax at and which limits the nonrefundable part of the federal child tax credit Oklahoma takes a share of. At least federalTax. How it is read.	Not income: a federal figure, at least federalTax (the tax after the nonrefundable credits); a household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field; 400 when federalTax is larger.
`federalRefundableCredits` also `federal_refundable_credits`	number	no	not supplied (none)	The year's federal refundable credits (Form 1040 lines 27a, 28, 29 and 30, and Schedule 3 line 13a), which Alabama's federal income tax deduction subtracts. How it is read.	Not income: a federal figure read with federalTax; a household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`localTaxRate` also `local_tax_rate`	number	no	the population-weighted average of the county rates	Indiana and Maryland only: the filer's county income tax rate as a fraction, within the state's lowest and highest official county rate. Elsewhere, or out of range, refused with 400. How it is read.	Not an amount: a rate (fraction) replacing the average county rate.	Indiana and Maryland only, within that state's lowest and highest official county rate (config.local_tax_rate_min and local_tax_rate_max on GET /api/state-tax/rules; the schema's range covers both states). Any other state, or out of range: 400. null = absent.
`localities`	array	no	none (Indiana and Maryland: the average county rate)	The local income-tax jurisdictions of the household, by official code (GET /api/state-tax/localities?state=XX lists them; never guessed from a zip code): the residence's county, city, school district or municipality, and (role "work") a workplace with the wages earned there. Each is taxed on its own base: NYC, Yonkers and Iowa school districts on the state return (in tax), the others on separate local returns (in totalTax). Engine 1.13.0: with residency, a county or Iowa school district on a part-year return, a nonresident's workplaces, and (residentFrom / residentTo / residentIncome) a part-year resident of NYC, Yonkers, a PA EIT subdivision or an Ohio earned-income-base district; the localities whose part-year rules are not settled are refused with the reason. How it is read.	Facts about where the household lives and works.	At most 6 entries, each a code string or {code, role, wages}; a code of another state, an unknown or unmodelled one, two residences of one kind, a workplace for a tax on residents only, wages on a residence, or workplace wages above the household's wages: 400. null = absent.
`localities[].code`	string	no	required	The jurisdiction's code (MD-0300, IN-49, IA-01-0018, OH-SD-0203, OH-MU-00142, PA-PSD-010101, MI-DETROIT, NY-NYC, KY-LOUISVILLE, MO-KANSAS-CITY, OR-METRO, DE-WILMINGTON, ...), any case. How it is read.	Which jurisdiction.	Required in an object; must be one of the listed codes of the request's state.
`localities[].role`	string	no	resident	"resident" (the household lives there) or "work" (a nonresident's workplace: its nonresident rate on the wages given). How it is read.	Residence or workplace.	resident or work; anything else: 400.
`localities[].wages`	number	no	0	A workplace's wages: what the household earned there. How it is read.	A subset of the household's wages.	A workplace only; non-negative; all workplaces together at most the household's wages.
`localities[].residentFrom` also `resident_from`	string	no	the whole year (or a part-year return's resident period)	Engine 1.13.0: the first day lived in this resident locality, YYYY-MM-DD in 2026: a part-year resident of it (NYC and Yonkers IT-360.1, a PA EIT subdivision's Local Worksheet, an Ohio earned-income-base school district). Not for a county or Iowa school district (they follow one day of residence) or a workplace. How it is read.	The period lived there.	With residentTo; inside a part-year return's resident period; the localities without a settled part-year rule refuse it: 400.
`localities[].residentTo` also `resident_to`	string	no	the whole year (or a part-year return's resident period)	Engine 1.13.0: the last day lived in this resident locality, YYYY-MM-DD in 2026. How it is read.	The period lived there.	With residentFrom: 400 otherwise.
`localities[].residentIncome` also `resident_income`	object	no	none (needed for a part-year resident of NYC, Yonkers, Philadelphia, an Ohio municipality or earned-income-base district, Lexington, Metro or Multnomah)	Engine 1.13.0: the income received while living there, under the keys of residency.stateIncome (IT-360.1 Columns B and C; SD 100 lines 29-32). How it is read.	Each a part of the year's amount.	A part-year resident of those localities only (a PA EIT subdivision, an Ohio traditional-base district and Kansas City / St. Louis take the period instead); each amount at most the year's: 400.
`localities[].residentIncome.wages`	number	no	0	The wages received while living in the locality. How it is read.	A part of the year's wages.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].residentIncome.ordinaryIncome` also `ordinary_income`	number	no	0	The ordinaryIncome received while living in the locality. How it is read.	A part of the year's ordinaryIncome.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].residentIncome.shortTermGains` also `short_term_gains`	number	no	0	The shortTermGains received while living in the locality. How it is read.	A part of the year's shortTermGains.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].residentIncome.capitalGains` also `capital_gains`	number	no	0	The capitalGains received while living in the locality. How it is read.	A part of the year's capitalGains.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].residentIncome.capitalLoss` also `capital_loss`	number	no	0	The capitalLoss received while living in the locality. How it is read.	A part of the year's capitalLoss.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].residentIncome.iraDistributions` also `ira_distributions`	number	no	0	The iraDistributions received while living in the locality. How it is read.	A part of the year's iraDistributions.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].residentIncome.pensionPrivate` also `pension_private`	number	no	0	The pensionPrivate received while living in the locality. How it is read.	A part of the year's pensionPrivate.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].residentIncome.pensionPublic` also `pension_public`	number	no	0	The pensionPublic received while living in the locality. How it is read.	A part of the year's pensionPublic.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].residentIncome.rothConversion` also `roth_conversion`	number	no	0	The rothConversion received while living in the locality. How it is read.	A part of the year's rothConversion.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].residentIncome.socialSecurity` also `social_security`	number	no	0	The socialSecurity received while living in the locality. How it is read.	A part of the year's socialSecurity.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].residentIncome.socialSecurityGross` also `social_security_gross`	number	no	0	The socialSecurityGross received while living in the locality. How it is read.	A part of the year's socialSecurityGross.	A finite number from 0 to the year's amount (at most $100 billion): 400. null = absent.
`localities[].daysOutside` also `days_outside`	integer	no	none (needed for a part-year resident of Kansas City or St. Louis)	Engine 1.14.0: the days the city's non-residency deduction formula deducts for a part-year resident: Kansas City (Form RD-109NR line 2) the days worked outside the city while not living in it ("You may not deduct days lived in the City"); St. Louis (Form E-1) the days lived or worked outside the City. The deduction is the year's wages x daysOutside / the work days, at the city's rate. How it is read.	At most the work days.	A whole number 0 to 365, only on a part-year Kansas City or St. Louis residence (with residentFrom / residentTo), at most the work days: 400.
`localities[].workDays` also `work_days`	integer	no	260 (both cities' standard work year)	Engine 1.14.0: St. Louis Form E-1 line 1, total work days ("standard work year is 260 days"); Kansas City's RD-109NR line 1 is always 260 ("Enter 260 for days worked everywhere"), so it is refused there. How it is read.	The formula's denominator.	A whole number 1 to 365, only on a part-year St. Louis residence: 400.
`otherLocalTaxCredit` also `other_local_tax_credit`	number	no	0	A resident's credit for local income tax paid to another locality, as the residence's ordinance allows it (each municipality sets its own; the engine never computes it, except between two Pennsylvania Act 32 jurisdictions, whose statutory credit it applies itself). Applied against the separate resident local returns, in the order given, at most each one's tax. How it is read.	An amount the caller computed from the ordinance.	Non-negative; needs a residence in localities that files a separate local return, else 400.
`localUnearnedIncome` also `local_unearned_income`	number	no	0	Philadelphia residents: the income its School Income Tax reaches (dividends, interest other than bank-deposit and government-bond interest, gains on assets held six months or less, annuities not from an employer plan, rents not under the Net Profits Tax); pensions and Social Security are not in it. Never derived from the other amounts. How it is read.	Overlaps ordinaryIncome, shortTermGains and qualifiedDividends; it is a separate base, not added income.	Non-negative; needs localities ["PA-PSD-510101"], else 400.
`propertyTaxPaid` also `property_tax_paid`	number	no	0	The year's property tax on the principal residence (a married filer on a separate return: their share). The states' property-tax credits and NJ's deduction read it. How it is read.	A fact for the credits, not income.	Non-negative; null = absent.
`rentPaid` also `rent_paid`	number	no	0	The year's rent for the principal residence. The renter's credits and the rent share of the property-tax credits read it. How it is read.	A fact for the credits, not income.	Non-negative; null = absent.
`rentIncludesHeat` also `rent_includes_heat`	boolean	no	false	The rent includes heat or utilities (NY's real property tax credit then counts a reduced share of it). How it is read.	A fact about rentPaid.	true or false; needs rentPaid, else 400.
`homeValue` also `home_value`	number	no	not said (no value limit applied)	The home's value: the assessed value (MA Senior Circuit Breaker limit) or full value (NY real property tax credit limit). How it is read.	A fact for the credits.	Non-negative; null = absent.
`taxExemptInterest` also `tax_exempt_interest`	number	no	0	Federally tax-exempt interest: counted in the household-income measures of the property-tax and senior credits. How it is read.	Not in ordinaryIncome; not taxed.	Non-negative; null = absent.
`medicalExpenses` also `medical_expenses`	number	no	0	The household's unreimbursed medical care expenses for the year (filer, spouse and dependents), insurance premiums included as IRC 213 counts them: New Jersey's medical expense deduction and New Mexico's medical care exemption and credit for a filer or spouse 65 or older. How it is read.	A fact for those rules.	Non-negative; null = absent.
`pensionPublicSsCovered` also `pension_public_ss_covered`	boolean	no	unknown	Was the pensionPublic service covered by Social Security? false unlocks the rules for non-covered pensions (each state page's public-pension section says which apply); true or absent gives none. It covers both spouses' pensionPublic. How it is read.	A fact about pensionPublic (both spouses').	true or false; null = absent (unknown). Anything else: 400.
`blind`	boolean	no	false	The primary filer is blind (the federal test: corrected vision no better than 20/200 in the better eye, or a field of 20 degrees or less). Each state's blind amounts apply as its page lists; true or false, null means false. How it is read.	A fact about the primary filer.	true or false; null = false. Anything else: 400.
`disabled`	boolean	no	false	The primary filer is totally and permanently disabled. Read only by the disability rules each state page lists; true or false, null means false. How it is read.	A fact about the primary filer.	true or false; null = false. Anything else: 400.
`spouse`	object	no	none (household totals)	Joint returns: the spouse's own amounts, age and facts; with it, the top-level person fields are the primary filer's own amounts. Married filing separately: only the other spouse's age and blind. How it is read.	Joint returns: makes the top-level person fields the primary's own. Separate returns: the other spouse's age and blind only.	An object with only the spouse keys listed here (any other key: 400); only with filingStatus mfj, or mfs with age and blind only, else 400.
`spouse.age`	number	no	the primary filer's age	Whole number, 1 to 120 (on a separate return: the other spouse's age). How it is read.	The spouse's age.	Whole number 1 to 120, else 400.
`spouse.wages`	number	no	0	The spouse's own wages (with computeFederal: the spouse's W-2 wages). How it is read.	Component. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.iraDistributions` also `spouse.ira_distributions`	number	no	0	The spouse's own IRA distributions. How it is read.	Component, disjoint from employerPlanDistributions and rothConversion. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.pensionPrivate` also `spouse.pension_private`	number	no	0	The spouse's own private pension. How it is read.	Component, disjoint from disabilityIncome. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.pensionPublic` also `spouse.pension_public`	number	no	0	The spouse's own public pension. How it is read.	Component, disjoint from pensionFederalCivilService and pensionMilitary. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.pensionMilitary` also `spouse.pension_military`	number	no	0	The spouse's own military retirement pay. How it is read.	Component. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.rothConversion` also `spouse.roth_conversion`	number	no	0	The spouse's own conversion. How it is read.	Component, not part of iraDistributions. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.blind`	boolean	no	false	The spouse is blind (joint returns; on a separate return, the other spouse). How it is read.	A fact about the spouse.	true or false; null = false. Anything else: 400.
`spouse.disabled`	boolean	no	false	The spouse is totally and permanently disabled (joint returns). How it is read.	A fact about the spouse.	true or false; null = false. Anything else: 400.
`dependents`	array	no	none	The household's dependents (people claimed as dependents on the federal return), each `{age, student, disabled}`; a head of household lists the qualifying person when that person is a dependent. The states' dependent exemptions, deductions and credits read it. How it is read.	Facts about the household's dependents.	An array of at most 20 objects with only age, student and disabled; [] = none; null = absent. Otherwise 400 naming the element.
`dependents[].age`	number	no	required	Whole number, 0 to 120: the age at the end of the year (0 for a child born in the year). How it is read.	A dependent's age.	Required: whole number 0 to 120, else 400.
`dependents[].student`	boolean	no	false	A full-time student (the five-month test). How it is read.	A fact about the dependent.	true or false; null = false. Anything else: 400.
`dependents[].disabled`	boolean	no	false	Permanently and totally disabled. How it is read.	A fact about the dependent.	true or false; null = false. Anything else: 400.
`pensionFederalCivilService` also `pension_federal_civil_service`	number	no	0	A federal civil service annuity (CSRS or FERS), counted as a public pension and read by the states' civil service rules. Do not also include it in pensionPublic. How it is read.	Component, disjoint from pensionPublic. With spouse: the primary filer's own amount (spouse.pensionFederalCivilService is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`disabilityIncome` also `disability_income`	number	no	0	Taxable disability pay of a person retired on disability (reported federally as wages before the minimum retirement age, or as a pension), counted as pension income and read by the states' disability-pay exclusions. Do not also include it in pensionPrivate. How it is read.	Component, disjoint from pensionPrivate. With spouse: the primary filer's own amount (spouse.disabilityIncome is the spouse's); without: the household total.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`earlyDistributions` also `early_distributions`	number	no	every IRA and employer-plan dollar of a person under 59	The part of iraDistributions and employerPlanDistributions taken before age 59½. How it is read.	Part of the same person's iraDistributions plus employerPlanDistributions; not added to income again.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. At most iraDistributions plus employerPlanDistributions (same person), else 400.
`earlyDistributionException` also `early_distribution_exception`	string	no	none (death for survivor benefits, disability for a disabled person)	The federal early-withdrawal exception for earlyDistributions: none, sepp (equal periodic payments), death (paid to a beneficiary), disability or other. How it is read.	A fact about earlyDistributions.	none, sepp, death, disability or other, any case; null = absent. Anything else: 400.
`iraBasis` also `ira_basis`	number	no	0	After-tax IRA contributions not yet recovered (a state that taxes an early distribution only above them reads it). How it is read.	Not income: the after-tax basis read with earlyDistributions; adds nothing to income.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`survivorBenefits` also `survivor_benefits`	boolean	no	false	The person's pension and IRA income is received as a beneficiary of someone who died. How it is read.	A fact about the person's pension and IRA income.	true or false; null = false. Anything else: 400.
`socialSecurityDisability` also `social_security_disability`	boolean	no	not said	The person's Social Security is disability benefits for the whole year; false says it is not (a state that exempts only older recipients then taxes a younger one's share). How it is read.	A fact about the person's Social Security.	true or false; null = not said. Anything else: 400.
`priorHohQualifyingPersonDied` also `prior_hoh_qualifying_person_died`	boolean	no	false	The filer was a head of household in one of the two previous years for a qualifying person who died in one of those years. How it is read.	A fact about the filer.	true or false; null = false. Anything else: 400.
`planMinimumRetirementAge` also `plan_minimum_retirement_age`	integer	no	not said (Connecticut reads disability pay as wages, Maine as pension income from 55, Ohio deducts it until 65)	The minimum retirement age of the plan paying the person's disabilityIncome: from that age the pay is a pension (IRS Pub. 525). Connecticut then subtracts it as a pension (line 48b), Maine counts it as pension income from that age (in place of 55), and Ohio stops deducting it on line 42 from that age (in place of 65). Every other state ignores it. How it is read.	A fact about the person's disabilityIncome. With spouse: the primary filer's (spouse.planMinimumRetirementAge is the spouse's); without: the household's.	Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs disabilityIncome at the same level (else 400).
`deceasedSpouseAge` also `deceased_spouse_age`	integer	no	not said (South Carolina's lower amount)	For a surviving spouse (survivorBenefits: true): the age the deceased spouse would have reached by the end of the year had they lived. South Carolina's surviving-spouse deduction (SC1040 line p-3) is $10,000 instead of $3,000 when that age is 65 or more. Every other state ignores it. How it is read.	A fact about the person's survivor income. With spouse: the primary filer's (spouse.deceasedSpouseAge is the spouse's); without: the household's.	Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs survivorBenefits: true at the same level (else 400).
`socialSecuritySurvivor` also `social_security_survivor`	boolean	no	false	The person's Social Security benefits are survivor benefits (paid because of the death of the person entitled to them). Colorado's death-benefit subtraction for a person under 55 then also covers the person's taxable Social Security, within its one $20,000 limit. Every other state ignores it. How it is read.	A fact about the person's Social Security. With spouse: the primary filer's (the spouse's own benefits are spouse.socialSecurityGross's share); without: the household's.	true or false; null = false. Anything else: 400.
`includeSources` also `include_sources`	boolean	no	true	false leaves rules.sources and rules.unsourced out of the response, for callers that do not need the citations (a smaller, faster response); the tax and every other field are the same. How it is read.	Not an engine input: shapes the response only.	true or false; null = true. Anything else: 400.
`spouse.pensionFederalCivilService` also `spouse.pension_federal_civil_service`	number	no	0	The spouse's own pensionFederalCivilService (joint returns). How it is read.	Component, disjoint from pensionPublic. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.disabilityIncome` also `spouse.disability_income`	number	no	0	The spouse's own disabilityIncome (joint returns). How it is read.	Component, disjoint from pensionPrivate. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.earlyDistributions` also `spouse.early_distributions`	number	no	every IRA and employer-plan dollar of a person under 59	The spouse's own earlyDistributions (joint returns). How it is read.	Part of the spouse's own iraDistributions plus employerPlanDistributions; not added to income again.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. At most spouse.iraDistributions plus spouse.employerPlanDistributions, else 400.
`spouse.earlyDistributionException` also `spouse.early_distribution_exception`	string	no	none (death for survivor benefits, disability for a disabled person)	The spouse's own earlyDistributionException (joint returns). How it is read.	A fact about earlyDistributions.	none, sepp, death, disability or other, any case; null = absent. Anything else: 400.
`spouse.iraBasis` also `spouse.ira_basis`	number	no	0	The spouse's own iraBasis (joint returns). How it is read.	Not income: the after-tax basis read with earlyDistributions; adds nothing to income.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.survivorBenefits` also `spouse.survivor_benefits`	boolean	no	false	The spouse's own survivorBenefits (joint returns). How it is read.	A fact about the spouse's pension and IRA income.	true or false; null = false. Anything else: 400.
`spouse.socialSecurityDisability` also `spouse.social_security_disability`	boolean	no	not said	The spouse's own socialSecurityDisability (joint returns). How it is read.	A fact about the spouse's Social Security.	true or false; null = not said. Anything else: 400.
`spouse.socialSecurityGross` also `spouse.social_security_gross`	number	no	half the household figure	The spouse's own gross Social Security (with their Tier 1 railroad benefits), part of socialSecurityGross (which must be given and at least as large). It divides the benefits between the spouses for the per-spouse rules (Colorado, Maine, Maryland, Rhode Island and the other rules that read each spouse's benefits). How it is read.	Part of socialSecurityGross (the household total); not added to income.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Needs socialSecurityGross and at most it, else 400.
`spouse.employerPlanDistributions` also `spouse.employer_plan_distributions`	number	no	0	The spouse's own 401(k), 403(b) and 457(b) distributions. How it is read.	Component, disjoint from iraDistributions. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.railroadRetirementTier1` also `spouse.railroad_retirement_tier1`	number	no	none of the household's Tier 1	The spouse's own part of railroadRetirementTier1 (needs it, at most it, and at most spouse.socialSecurityGross when that is given). How it is read.	Part of railroadRetirementTier1 and of spouse.socialSecurityGross.	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Needs railroadRetirementTier1 and at most it (and at most spouse.socialSecurityGross when given), else 400.
`spouse.railroadRetirementTier2` also `spouse.railroad_retirement_tier2`	number	no	0	The spouse's own Railroad Retirement Tier 2 and supplemental annuities. How it is read.	Component. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field.
`spouse.selfEmploymentIncome` also `spouse.self_employment_income`	number	no	0	The spouse's own net profit from self-employment (joint returns; needs computeFederal: true). How it is read.	Component, disjoint from spouse.wages. The spouse's own amount (joint returns).	Finite, from 0 to $100 billion; null = absent. Otherwise 400 naming the field. Not 0 without computeFederal: true, else 400.
`spouse.planMinimumRetirementAge` also `spouse.plan_minimum_retirement_age`	integer	no	not said	The spouse's own planMinimumRetirementAge (joint returns): the minimum retirement age of the plan paying spouse.disabilityIncome. How it is read.	A fact about the spouse's disabilityIncome.	Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs spouse.disabilityIncome (else 400); refused on a separate return.
`spouse.deceasedSpouseAge` also `spouse.deceased_spouse_age`	integer	no	not said	The spouse's own deceasedSpouseAge (joint returns): the age the spouse's deceased former spouse would have reached. How it is read.	A fact about the spouse's survivor income.	Whole number 1 to 120; null = absent. Otherwise 400 naming the field. Needs spouse.survivorBenefits: true (else 400); refused on a separate return.
`spouse.socialSecuritySurvivor` also `spouse.social_security_survivor`	boolean	no	false	The spouse's own socialSecuritySurvivor (joint returns): the spouse's Social Security benefits are survivor benefits. How it is read.	A fact about the spouse's Social Security.	true or false; null = false. Anything else: 400; refused on a separate return.
`computeFederal` also `compute_federal`	boolean	no	false (the caller's own federal figures, or none)	true: the federal inputs come from QuantCalc's federal engine instead of from the request. It builds one federal return from this request (wages, self-employment income, IRA and employer-plan distributions, pensions including Railroad Retirement Tier 2, Roth conversions, gains, gross Social Security, the ages) and hands the state engine what the planner hands it: socialSecurity (the taxable part), federalTax and federalTaxBeforeCredits (the income tax without the NIIT; the federal engine models no credits), federalNiit, federalRefundableCredits 0, and federal taxable income for the states whose base starts from it. The response gains a `federal` object with the federal return. blind (the filer, and the spouse on a joint return) adds the federal §63(f) amount for blindness, and filingStatus qss is priced on the federal joint tables for a qualifying surviving spouse. ordinaryIncome goes on federal Form 1040 line 2b (interest and non-qualified dividends) and qualifiedDividends on lines 3a and 3b, with their share of the NIIT and the capital-gains worksheet. Each person's wages are one W-2 from one employer (boxes 1, 3 and 5 the same, box 3 at most the social security wage base) with the employer's social security and Medicare withholding, including the additional Medicare withholding (federal engine 2.0); selfEmploymentIncome is the person's Schedule C net profit (Schedule SE, the deduction for half the self-employment tax, the qualified business income deduction), and the state engine receives each person's wages plus that profit less half the person's self-employment tax. The self-employment tax and the Additional Medicare Tax are not income tax: federalTax stays the income tax without them. A request with anything the federal engine does not model (disabilityIncome, earlyDistributions or earlyDistributionException, iraBasis, disabled, dependents, a separate filer's spouse.blind), or with its own socialSecurity or federal figures, is refused with 400. The embeddable library answers it the same way from library 1.6 (its default build carries the federal engine); a state-only build of the library ignores it. Federal engine reference: /docs/federal-tax/. With projection, the federal return is the federal engine's projection of the same year, with the same factor and indexing (federal engine 2.0), and the `federal` object carries rulesYear, projectedYear, projected and the federal projection block. How it is read.	Not an amount: chooses where federalTax, federalNiit, federalTaxBeforeCredits, federalRefundableCredits and socialSecurity come from. Needs age, and spouse.age on a joint return.	true or false; null = false. Anything else: 400.
`includeInputsNotSupplied` also `include_inputs_not_supplied`	boolean	no	true	false leaves inputsNotSupplied out of the response and runs none of its probes (engine 1.10.0). The tax is the same either way. How it is read.	Response shaping; not an amount.	true or false; null = true. Anything else: 400 naming the field.
`includeNotModelled` also `include_not_modelled`	boolean	no	true	false leaves notModelled out of the response (engine 1.12.0). The tax is the same either way. How it is read.	Response shaping; not an amount.	true or false; null = true. Anything else: 400 naming the field.
`strict`	boolean	no	false (unknown top-level keys are ignored)	true: a top-level key the API does not read is refused with a 400 that names it (up to five, then a count), checked before anything else (engine 1.10.0). Keys match as the API matches them: any case, either spelling. How it is read.	Request checking; not an amount.	true or false; null = false. Anything else: 400 naming the field.
`projection`	object	no	none: the rules year (2026)	Estimate a later tax year (engine 1.10.0): {"year": 2040, "inflation": 0.025} or {"year": 2040, "cpiFactor": 1.44}. Every dollar amount and birth-year age cutoff of the state's rules moves the way the state's law moves it (see /docs/state-tax/indexing/), or, with indexing "inflation", as QuantCalc's planner moved them before engine 1.10.0; the amounts in the request are taken as that year's. The response says projected: true and carries a projection block. With computeFederal the federal return is projected to the same year with the same factor and indexing (federal engine 2.0: see /docs/federal-tax/indexing/). How it is read.	Not an amount.	An object with year and exactly one of inflation or cpiFactor, and no other key; otherwise 400 naming the problem.
`projection.year`	integer	no	(required inside projection)	The tax year to estimate. How it is read.	Not an amount.	Required inside projection; a whole number from 2026 (the rules year) to 2100. Otherwise 400.
`projection.inflation`	number	no	none (then cpiFactor)	The annual CPI assumption; the cumulative factor is (1 + inflation) to the power of (year - 2026). How it is read.	Not an amount; exactly one of inflation and cpiFactor.	From -0.10 to 0.25; not together with cpiFactor. Otherwise 400.
`projection.cpiFactor` also `projection.cpi_factor`	number	no	none (then inflation)	Your own cumulative CPI factor from 2026 to year (for example 1.44). How it is read.	Not an amount; exactly one of inflation and cpiFactor.	From 0.01 to 100, and 1 when year is 2026; not together with inflation. Otherwise 400.
`projection.indexing`	string	no	law	How the dollar amounts move: "law" (the default) moves each the way its state's law moves it; "inflation" multiplies every amount QuantCalc's planner scaled before engine 1.10.0 by the factor, unrounded, and holds the rest (schedules and derived amounts not applied; the result is not refused for an unsettled amount). Birth-year age cutoffs move one year per year either way. How it is read.	Not an amount.	"law" or "inflation", any case; null means law. Otherwise 400.
`residency`	object	no	none: a full-year resident (every result before engine 1.12.0)	A part-year resident's or nonresident's return (engine 1.12.0): {"status": "partYear", "residentFrom": "2026-07-01", "residentTo": "2026-12-31", "stateIncome": {...}} or {"status": "nonresident", "stateIncome": {...}}. The top-level amounts stay the whole year's (the forms compute as if a full-year resident, then apportion); stateIncome holds the part the state taxes. Each state's own method (ratio, prorated items, rounding) is on its page; the response's residency block shows the computation. How it is read.	Not an amount; the whole year's amounts stay at the top level.	An object with status and only the keys listed here; with residency, dependents, the credit facts, and military, civil service, disability, employer-plan, self-employment, railroad or qualified-dividend amounts or the person facts are a 400 (not modelled with residency); a spouse split needs residency.spouse (engine 1.13.0); localities: see localities[] (engine 1.13.0).
`residency.status`	string	yes	(required inside residency)	resident (the full-year return), partYear or nonresident (case-insensitive). With residency.spouse: the primary's own. How it is read.	Not an amount.	Required inside residency; anything else: 400.
`residency.residentFrom` also `resident_from`	string	no	(required for partYear)	The first day of the resident period, YYYY-MM-DD in 2026. How it is read.	The resident period of a part-year return (the days and months the state counts).	A date of 2026 written YYYY-MM-DD, at most residentTo; required with residentTo for partYear, refused otherwise: 400.
`residency.residentTo` also `resident_to`	string	no	(required for partYear)	The last day of the resident period, YYYY-MM-DD in 2026. How it is read.	The resident period of a part-year return.	A date of 2026 written YYYY-MM-DD; required with residentFrom for partYear: 400.
`residency.stateIncome` also `state_income`	object	no	every amount 0 (no income from the state)	The amounts the state taxes: everything received while a resident plus the state-source income while a nonresident, under the same keys as the top level. How it is read.	Each a part of the top-level amount of the same key.	An object of the amount keys listed here only (any other key: 400); a full-year resident gives none (400).
`residency.stateIncome.wages`	number	no	0	The wages earned in the state or while a resident. How it is read.	A part of the top-level wages.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent.
`residency.stateIncome.ordinaryIncome` also `ordinary_income`	number	no	0	The interest, dividends and other income received while a resident (a nonresident: from a business or property in the state). How it is read.	A part of the top-level ordinaryIncome.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent.
`residency.stateIncome.shortTermGains` also `short_term_gains`	number	no	0	The net short-term gains taxed by the state. How it is read.	A part of the top-level shortTermGains.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent.
`residency.stateIncome.capitalGains` also `capital_gains`	number	no	0	The net long-term gains taxed by the state. How it is read.	A part of the top-level capitalGains.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent.
`residency.stateIncome.capitalLoss` also `capital_loss`	number	no	0	The the part of the net capital loss the state's column carries. How it is read.	A part of the top-level capitalLoss.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent.
`residency.stateIncome.iraDistributions` also `ira_distributions`	number	no	0	The IRA distributions received while a resident (a nonresident: 0, 4 U.S.C. §114). How it is read.	A part of the top-level iraDistributions.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400.
`residency.stateIncome.pensionPrivate` also `pension_private`	number	no	0	The private pensions received while a resident (a nonresident: 0). How it is read.	A part of the top-level pensionPrivate.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400.
`residency.stateIncome.pensionPublic` also `pension_public`	number	no	0	The public pensions received while a resident (a nonresident: 0). How it is read.	A part of the top-level pensionPublic.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400.
`residency.stateIncome.rothConversion` also `roth_conversion`	number	no	0	The Roth conversions made while a resident (a nonresident: 0). How it is read.	A part of the top-level rothConversion.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400.
`residency.stateIncome.socialSecurity` also `social_security`	number	no	0	The the taxable Social Security received while a resident (a nonresident: 0). How it is read.	A part of the top-level socialSecurity.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400.
`residency.stateIncome.socialSecurityGross` also `social_security_gross`	number	no	0	The the gross Social Security received while a resident (a nonresident: 0). How it is read.	A part of the top-level socialSecurityGross.	A finite number from 0 to the year's own amount of the same key (at most $100 billion); more: 400. null = absent. A nonresident's retirement income or Social Security: 400.
`residency.spouse`	object	no	none: the top-level residency is the household's (both spouses the same)	Engine 1.13.0: the spouse's own residency on a joint (mfj) request with the spouse object, when the two differ (one moves first): {"status", "residentFrom", "residentTo", "stateIncome"} with the same meaning as residency's own keys. With it, residency's own keys are the primary's, each stateIncome is that spouse's own part (each spouse's own amounts: the person amounts of the top level or spouse object, and their part of the household amounts per residency.spouseShare), and the state's own rule for the couple decides the returns (residency.couple in the response). How it is read.	Not an amount.	An object with status and only these keys; it needs filingStatus "mfj" and the spouse object: 400 otherwise.
`residency.spouse.status`	string	yes	(required inside residency.spouse)	The spouse's own residency: resident, partYear or nonresident (case-insensitive). How it is read.	Not an amount.	Required inside residency.spouse; anything else: 400.
`residency.spouse.residentFrom` also `resident_from`	string	no	(required for a partYear spouse)	The first day of the spouse's own resident period, YYYY-MM-DD in 2026. How it is read.	The spouse's resident period.	A date of 2026 written YYYY-MM-DD, at most residentTo; required with residentTo for partYear, refused otherwise: 400.
`residency.spouse.residentTo` also `resident_to`	string	no	(required for a partYear spouse)	The last day of the spouse's own resident period, YYYY-MM-DD in 2026. How it is read.	The spouse's resident period.	A date of 2026 written YYYY-MM-DD; required with residentFrom for partYear: 400.
`residency.spouse.stateIncome` also `state_income`	object	no	every amount 0 (no income from the state)	The spouse's own amounts the state taxes: everything the spouse received while a resident plus the spouse's state-source income while a nonresident (a full-year resident spouse gives none: all of the spouse's income is the state's). How it is read.	Each a part of the spouse's own amount.	The keys of residency.stateIncome; each at most the spouse's own amount: 400.
`residency.spouse.stateIncome.wages`	number	no	0	The spouse's own wages the state taxes. How it is read.	A part of the spouse's own wages.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouse.stateIncome.ordinaryIncome` also `ordinary_income`	number	no	0	The spouse's own ordinaryIncome the state taxes. How it is read.	A part of the spouse's own ordinaryIncome.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouse.stateIncome.shortTermGains` also `short_term_gains`	number	no	0	The spouse's own shortTermGains the state taxes. How it is read.	A part of the spouse's own shortTermGains.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouse.stateIncome.capitalGains` also `capital_gains`	number	no	0	The spouse's own capitalGains the state taxes. How it is read.	A part of the spouse's own capitalGains.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouse.stateIncome.capitalLoss` also `capital_loss`	number	no	0	The spouse's own capitalLoss the state taxes. How it is read.	A part of the spouse's own capitalLoss.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouse.stateIncome.iraDistributions` also `ira_distributions`	number	no	0	The spouse's own iraDistributions the state taxes. How it is read.	A part of the spouse's own iraDistributions.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouse.stateIncome.pensionPrivate` also `pension_private`	number	no	0	The spouse's own pensionPrivate the state taxes. How it is read.	A part of the spouse's own pensionPrivate.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouse.stateIncome.pensionPublic` also `pension_public`	number	no	0	The spouse's own pensionPublic the state taxes. How it is read.	A part of the spouse's own pensionPublic.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouse.stateIncome.rothConversion` also `roth_conversion`	number	no	0	The spouse's own rothConversion the state taxes. How it is read.	A part of the spouse's own rothConversion.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouse.stateIncome.socialSecurity` also `social_security`	number	no	0	The spouse's own socialSecurity the state taxes. How it is read.	A part of the spouse's own socialSecurity.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouse.stateIncome.socialSecurityGross` also `social_security_gross`	number	no	0	The spouse's own socialSecurityGross the state taxes. How it is read.	A part of the spouse's own socialSecurityGross.	A finite number from 0 to the spouse's own amount (at most $100 billion); a nonresident spouse's retirement amounts and Social Security must be 0 (4 U.S.C. 114): 400. null = absent.
`residency.spouseShare` also `spouse_share`	object	no	none (needed for each household amount that is not 0)	Engine 1.13.0: the spouse's part of the household amounts (ordinaryIncome, shortTermGains, capitalGains, capitalLoss, capitalLossCarryover, socialSecurity) when the spouses' residency differs; the primary's part is the rest. Each spouse's own amounts decide what the state taxes and each separate return. How it is read.	A split of the top-level household amounts.	Only with residency.spouse; each key needed when its household amount is not 0, at most it: 400.
`residency.spouseShare.ordinaryIncome` also `ordinary_income`	number	no	(needed when the household amount is not 0)	The spouse's part of the household ordinaryIncome. How it is read.	A part of the top-level ordinaryIncome.	A finite number from 0 to the household amount (at most $100 billion): 400. null = absent.
`residency.spouseShare.shortTermGains` also `short_term_gains`	number	no	(needed when the household amount is not 0)	The spouse's part of the household shortTermGains. How it is read.	A part of the top-level shortTermGains.	A finite number from 0 to the household amount (at most $100 billion): 400. null = absent.
`residency.spouseShare.capitalGains` also `capital_gains`	number	no	(needed when the household amount is not 0)	The spouse's part of the household capitalGains. How it is read.	A part of the top-level capitalGains.	A finite number from 0 to the household amount (at most $100 billion): 400. null = absent.
`residency.spouseShare.capitalLoss` also `capital_loss`	number	no	(needed when the household amount is not 0)	The spouse's part of the household capitalLoss. How it is read.	A part of the top-level capitalLoss.	A finite number from 0 to the household amount (at most $100 billion): 400. null = absent.
`residency.spouseShare.capitalLossCarryover` also `capital_loss_carryover`	number	no	(needed when the household amount is not 0)	The spouse's part of the household capitalLossCarryover. How it is read.	A part of the top-level capitalLossCarryover.	A finite number from 0 to the household amount (at most $100 billion): 400. null = absent.
`residency.spouseShare.socialSecurity` also `social_security`	number	no	(needed when the household amount is not 0)	The spouse's part of the household socialSecurity. How it is read.	A part of the top-level socialSecurity.	A finite number from 0 to the household amount (at most $100 billion): 400. null = absent.
`residency.election`	string	no	none: the state's required or default treatment, else (a free choice) the joint return the request's mfj names	Engine 1.13.0: which of the treatments the state allows the couple applies to tax: "joint" (one joint part-year / nonresident return), "separate" (each spouse's own return) or "jointAsResidents" (a joint resident return, both taxed as full-year residents). Every allowed treatment is computed and reported either way (residency.couple.options). How it is read.	Not an amount.	Only with residency.spouse; one the state allows for the couple: 400 otherwise.
`rentalNetIncome` also `rental_net_income`	number	no	not supplied (none)	Rental real estate, signed: the federal Schedule E line 26 amount (Schedule 1 line 5), net rental income or the loss the federal return allows after the passive-activity limit (Form 8582). A profit is other ordinary income (and joins Georgia's and Delaware's retirement-income exclusions, which name net rental income); a loss reduces the state's income where the state starts from federal AGI or follows the federal schedule, and offsets no other income in Pennsylvania and New Jersey. How it is read.	A household total; not part of ordinaryIncome. With computeFederal the federal return takes it as Schedule E line 26 as given.	Finite, from -$100 billion to $100 billion; null = absent. Refused with residency and for a part-year resident of a locality.

All amounts are annual US dollars, finite, not negative and at most $100 billion. Most income fields are components: separate amounts that do not overlap, each added to income once. A few are part of another field and are never added again: socialSecurity and railroadRetirementTier1 are parts of socialSecurityGross; earlyDistributions is part of the same person's iraDistributions plus employerPlanDistributions; spouse.socialSecurityGross and spouse.railroadRetirementTier1 are the spouse's parts of the household figures. iraBasis, federalTax, federalNiit, federalTaxBeforeCredits and federalRefundableCredits are not income at all, and planMinimumRetirementAge, deceasedSpouseAge and socialSecuritySurvivor are facts about a person's income. The column above says which is which; see income types for where each dollar goes. Every field added after the first release is optional. A request that omits them is computed as it was before they existed, except where a later release corrected a rule that applies to it (each correction is in the changelog). Every key of more than one word is also accepted in snake_case (ordinary_income, filing_status, survivor_benefits and so on), and keys are matched without regard to case. Unknown top-level keys are ignored unless the request says "strict": true (below); unknown keys inside spouse, a dependent or projection are always refused. The JSON Schema encodes every row of this table.

The input most often wrong

socialSecurity is the federally taxable part of benefits (the amount in federal AGI), not the gross benefit. States that tax benefits start from that figure, so gross benefits overstate the base in every state that taxes any of them. Send gross benefits separately as socialSecurityGross.

Strict requests

With "strict": true, a top-level key the API does not read is a 400 that names it (up to five, then a count), so a misspelt field (iraDistribution for iraDistributions) is refused instead of silently absent. Keys are matched the way the API matches them: without regard to case, in either spelling. Without strict (or with false) unknown top-level keys are ignored, as they always have been.

{
  "state": "CA",
  "filingStatus": "single",
  "age": 67,
  "iraDistribution": 30000,
  "strict": true
}

HTTP 400
{
  "error": "strict: not a field of this API: \"iraDistribution\" (check the spelling, or leave strict out to ignore unknown keys)"
}

Later tax years: projection

The engine's rules are those of tax year 2026. "projection": {"year": 2040, "inflation": 0.025} estimates a later year: year is the tax year (2026 to 2100), and exactly one of inflation (an annual CPI assumption from -0.10 to 0.25; the factor is (1 + inflation)^{year − 2026}) or cpiFactor (your own cumulative factor from 2026, 0.01 to 100; it must be 1 for 2026 itself). Every dollar amount and birth-year age cutoff of the state's rules then moves the way the state's law moves it: indexed amounts by the factor with the statute's rounding, fixed-in-law amounts not at all, enacted schedules by their schedule (the method; each state page lists its rules and their sources). The amounts you send are taken as that year's amounts. Rates and the rules themselves stay the 2026 ones. "indexing": "inflation" instead moves the amounts as QuantCalc's planner did before September 2026, every amount it scaled rising with the factor whatever the law says (the two modes); "law" is the default.

A response to a request with projection carries rulesYear (2026), projectedYear and projected (true when the year is after 2026; for 2026 itself the result is the 2026 one and projected is false), and a projection block: the factor used, every amount that bore on this result (an amount bears when setting it to zero, or far above its value, would change the tax) with its 2026 and projected values, the rule that moved it, its method and multiplier, the rules with their statements and sources (both left out with "includeSources": false), the state's dollar tables held in code, what the projection does not apply, and the changes the state has enacted for later years that it does not apply. Show the result as an estimate on 2026 rules. taxYear stays "2026", the year of the rules.

Refused with a 400: a year or factor outside the ranges above, both or neither of inflation and cpiFactor, an unknown key inside projection, a result that depends on an amount whose later-year treatment no official source settled. computeFederal with projection is priced: the federal engine projects the federal return to the same year with the same factor and indexing (federal indexing), and the federal object says so (projected, projectedYear and its own projection block).

{
  "state": "CA",
  "filingStatus": "single",
  "age": 67,
  "pensionPrivate": 48000,
  "iraDistributions": 12000,
  "socialSecurity": 20400,
  "socialSecurityGross": 24000,
  "projection": {
    "year": 2040,
    "inflation": 0.025
  }
}

Returns tax $691.21 for 2040 (the same household on 2026 rules: $1,415.08).

The projection block of the response

{
  "rulesYear": 2026,
  "projectedYear": 2040,
  "cpiFactor": 1.4129738209737657,
  "inflation": 0.025,
  "indexing": "law",
  "parameters": [
    {
      "parameter": "brackets_single",
      "rule": "ca-brackets",
      "method": "cpi",
      "rulesYearValue": [
        [
          0,
          11456,
          0.01
        ],
        [
          11456,
          27157,
          0.02
        ],
        [
          27157,
          42861,
          0.04
        ],
        [
          42861,
          59498,
          0.06
        ],
        [
          59498,
          75197,
          0.08
        ],
        [
          75197,
          384109,
          0.093
        ],
        [
          384109,
          460927,
          0.103
        ],
        [
          460927,
          768213,
          0.113
        ],
        [
          768213,
          null,
          0.123
        ]
      ],
      "projectedValue": [
        [
          0,
          16187,
          0.01
        ],
        [
          16187,
          38372,
          0.02
        ],
        [
          38372,
          60561,
          0.04
        ],
        [
          60561,
          84069,
          0.06
        ],
        [
          84069,
          106251,
          0.08
        ],
        [
          106251,
          542736,
          0.093
        ],
        [
          542736,
          651278,
          0.103
        ],
        [
          651278,
          1085465,
          0.113
        ],
        [
          1085465,
          null,
          0.123
        ]
      ],
      "multiplier": 1.4129738209737657
    },
    {
      "parameter": "std_deduction_single",
      "rule": "ca-standard-deduction",
      "method": "cpi",
      "rulesYearValue": 5900,
      "projectedValue": 8337,
      "multiplier": 1.4129738209737657
    },
    {
      "parameter": "exemption_credit_per",
      "rule": "ca-exemption-credits",
      "method": "cpi",
      "rulesYearValue": 158,
      "projectedValue": 223,
      "multiplier": 1.4129738209737657
    },
    {
      "parameter": "senior_credit_per",
      "rule": "ca-exemption-credits",
      "method": "cpi",
      "rulesYearValue": 158,
      "projectedValue": 223,
      "multiplier": 1.4129738209737657
    },
    {
      "parameter": "credit_senior_min_age",
      "rule": "ca-senior-credit-age",
      "method": "age",
      "rulesYearValue": 65,
      "projectedValue": 65
    },
    {
      "parameter": "top_surtax_threshold",
      "rule": "ca-mental-health-surtax",
      "method": "fixed",
      "rulesYearValue": 1000000,
      "projectedValue": 1000000
    }
  ],
  "codeTables": [
    {
      "table": "ca-caleitc",
      "rule": "credit-ca-caleitc",
      "method": "cpi"
    }
  ],
  "rules": {
    "ca-brackets": {
      "method": "cpi",
      "index": "California Consumer Price Index (all items), change from June of the prior year to June of the current year, applied to the preceding year's amounts",
      "rounding": {
        "mode": "nearest",
        "step": 1
      },
      "establishes": "RTC 17041(h): each year FTB multiplies the preceding year's brackets by the California CPI (June-to-June) inflation factor and rounds to the nearest $1 (joint brackets are twice the single under 17045). Engine 1.12.0 carries the FTB's published 2026 brackets.",
      "sources": [
        {
          "url": "https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?lawCode=RTC&sectionNum=17041",
          "title": "Cal. Rev. & Tax. Code § 17041",
          "kind": "statute",
          "official": true,
          "quote": "the percentage change in the California Consumer Price Index for all items from June of the prior calendar year to June of the current calendar year",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20261001124816id_/https://www.ftb.ca.gov/about-ftb/newsroom/tax-news/index.html",
          "title": "Tax News, October 2026: 2026 Indexing (Internet Archive copy of the current edition)",
          "kind": "agency_page",
          "official": true,
          "quote": "2026 California tax rate schedules",
          "checked": "2026-10-12"
        }
      ]
    },
    "ca-standard-deduction": {
      "method": "cpi",
      "index": "California Consumer Price Index (all items), change from June of the prior year to June of the current year, applied to the preceding year's amounts",
      "rounding": {
        "mode": "nearest",
        "step": 1
      },
      "establishes": "RTC 17073.5(d): the standard deduction ($1,880 / $3,760 base; HOH and joint twice the single) is recomputed each year by the California CPI factor and rounded to the nearest $1. Engine 1.12.0 carries the FTB's published 2026 amounts ($5,900 / $11,800).",
      "sources": [
        {
          "url": "https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?lawCode=RTC&sectionNum=17073.5",
          "title": "Cal. Rev. & Tax. Code § 17073.5",
          "kind": "statute",
          "official": true,
          "quote": "shall multiply the standard deduction amounts in the preceding taxable year by the inflation adjustment factor determined in paragraph (2), and round off the resulting products to the nearest one dollar ($1).",
          "checked": "2026-09-30"
        },
        {
          "url": "https://web.archive.org/web/20261001124816id_/https://www.ftb.ca.gov/about-ftb/newsroom/tax-news/index.html",
          "title": "Tax News, October 2026: 2026 Indexing (Internet Archive copy of the current edition)",
          "kind": "agency_page",
          "official": true,
          "quote": "Standard deduction for single or married filing separate taxpayers $5,706 $5,900",
          "checked": "2026-10-12"
        }
      ]
    },
    "ca-exemption-credits": {
      "method": "cpi",
      "index": "California Consumer Price Index (all items), change from June of the prior year to June of the current year, applied to the preceding year's amounts",
      "rounding": {
        "mode": "nearest",
        "step": 1
      },
      "establishes": "RTC 17054(i): the personal, age-65, blind and dependent exemption credits are recomputed each year by the California CPI factor, rounded to the nearest $1 (the joint credit is twice the single). Engine 1.12.0 carries the FTB's published 2026 amounts ($158 personal and senior, $491 dependent).",
      "sources": [
        {
          "url": "https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?lawCode=RTC&sectionNum=17054",
          "title": "Cal. Rev. & Tax. Code § 17054",
          "kind": "statute",
          "official": true,
          "quote": "shall multiply the immediately preceding taxable year credits by the inflation adjustment factor determined in paragraph (2), and round off the resulting products to the nearest one dollar ($1).",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20261001124816id_/https://www.ftb.ca.gov/about-ftb/newsroom/tax-news/index.html",
          "title": "Tax News, October 2026: 2026 Indexing (Internet Archive copy of the current edition)",
          "kind": "agency_page",
          "official": true,
          "quote": "Personal exemption credit amount for single, separate, and head of household taxpayers $153 $158",
          "checked": "2026-10-12"
        }
      ]
    },
    "ca-senior-credit-age": {
      "method": "age",
      "establishes": "The senior exemption credit is for an individual 65 years of age or over by the end of the taxable year: a fixed attained age.",
      "sources": [
        {
          "url": "https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?lawCode=RTC&sectionNum=17054",
          "title": "Cal. Rev. & Tax. Code § 17054",
          "kind": "statute",
          "official": true,
          "quote": "in the case of an individual who is 65 years of age or over by the end of the taxable year",
          "checked": "2026-10-12"
        }
      ]
    },
    "ca-mental-health-surtax": {
      "method": "fixed",
      "establishes": "RTC 17043: the 1% additional tax applies to taxable income over $1,000,000; the section expressly excludes the 17041 bracket recomputation, so the threshold is fixed for every filing status.",
      "sources": [
        {
          "url": "https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?lawCode=RTC&sectionNum=17043",
          "title": "Cal. Rev. & Tax. Code § 17043",
          "kind": "statute",
          "official": true,
          "quote": "in excess of one million dollars ($1,000,000)",
          "checked": "2026-10-12"
        }
      ]
    },
    "credit-ca-caleitc": {
      "method": "cpi",
      "index": "California Consumer Price Index (17041(h))",
      "rounding": {
        "mode": "nearest",
        "step": 1
      },
      "establishes": "R&TC 17052: the CalEITC amounts are recomputed annually (17041(h)); the engine carries the 2025 table, the 2026 one not yet published.",
      "sources": [
        {
          "url": "https://www.ftb.ca.gov/forms/2025/2025-3514-booklet.pdf",
          "title": "2025 Instructions for Form FTB 3514, California Earned Income Tax Credit (incl. EITC Table)",
          "kind": "agency_page",
          "official": true,
          "quote": "$1 $50 2 7 9 10",
          "checked": "2026-10-12"
        }
      ]
    }
  },
  "notApplied": [
    "Rates, percentages and the rules themselves are the rules year's, except a whole bracket table a statute prints for a later year, which applies with its rates; otherwise only dollar amounts and birth-year age cutoffs are projected.",
    "cpiFactor stands in for every index the statutes name (CPI-U, chained CPI-U, a state CPI, the maximum Social Security benefit, the poverty guideline); each increase is rounded the statute's way from the rules-year amount, so a projected figure can differ from the one the state publishes by the difference between the indexes and by one rounding step."
  ],
  "enactedChangesNotApplied": []
}

What the request did not supply

inputsNotSupplied lists the facts and splits the API accepts that the request did not give and that could change this result: for each, the engine evaluates the request again with the input set to each of a fixed set of probe values (the projection included), and lists it when a probe changes the tax, the total with the separate local returns, or the net tax after the refundable credits. Each entry names the input, the rule family (the keys of rules.sources), what the engine assumed without it, what was probed, taxMin / taxMax: the lowest and highest tax over the probes and the result as given, and totalTaxMin / totalTaxMax, the same for totalTax (a local tax filed on its own return moves only that), and netTaxMin / netTaxMax, the same for netTax (a refundable credit moves only that). An empty list means no probed value of any candidate changed either. Income amounts that are simply absent (no wages, no gains) are not listed: absent means none. The spouse's own facts are not probed, except the spouse's age, blindness, disability and share of the gross benefits. With computeFederal each probe also re-runs the federal engine. "includeInputsNotSupplied": false leaves the list out and runs no probes.

Response

The response to the request above, as the engine returns it:

{
  "state": "AL",
  "stateName": "Alabama",
  "tax": 1570,
  "effectiveRate": 0.01585858585858586,
  "totalTax": 1570,
  "refundableCredits": {
    "total": 0,
    "items": []
  },
  "netTax": 1570,
  "input": {
    "filingStatus": "mfj",
    "age": 67,
    "ordinaryIncome": 0,
    "socialSecurity": 28000,
    "capitalGains": 5000,
    "iraDistributions": 30000,
    "pensionPublic": 24000,
    "socialSecurityGross": 36000,
    "spouse": {
      "age": 64,
      "wages": 0,
      "iraDistributions": 12000,
      "pensionPrivate": 0,
      "pensionPublic": 0,
      "pensionMilitary": 0,
      "rothConversion": 0
    }
  },
  "rules": {
    "taxesSocialSecurity": false,
    "socialSecurityRule": "exempt",
    "bracketCount": 3,
    "standardDeduction": 8500,
    "personalExemption": 3000,
    "seniorSubtraction": 0,
    "seniorSubtractionMinAge": 0,
    "capitalGainsTaxedAsOrdinary": true,
    "capitalGainsInclusionRatio": 1,
    "retirementIncomeExclusion": {
      "cap": 12000,
      "minAge": 65,
      "partialCap": 0,
      "partialMinAge": 0,
      "incomeLimit": 0,
      "reducedBySocialSecurity": false
    },
    "militaryRetirement": {
      "treatment": "exempt",
      "cap": null,
      "minAge": 0,
      "capBelowMinAge": null,
      "percentExempt": null,
      "incomeLimit": null,
      "incomeLimitPhaseoutRange": null,
      "sharesGeneralExclusion": true,
      "earnedIncomeBonus": null,
      "earnedIncomeThreshold": null,
      "reducedBySocialSecurity": false,
      "creditRate": null,
      "perTaxpayer": true
    },
    "wages": {
      "treatment": "ordinary_income",
      "earnedIncomeInRetirementExclusion": null
    },
    "localTax": {
      "included": false,
      "rate": null,
      "basis": "none"
    },
    "sources": {
      "rates": [
        {
          "url": "https://www.revenue.alabama.gov/tax-types/individual-income-tax/",
          "title": "Individual Income Tax",
          "kind": "agency_page",
          "official": true,
          "quote": "2 percent on first $500 of taxable income",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
          "title": "Alabama Department of Revenue: 25f40bk.pdf",
          "kind": "instructions",
          "official": true,
          "quote": "Amount on Page 1, Line 10 Dependent Exemption 0 - 50,000 50,001 - 100,000 Over 100,000 1,000 500 300",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40.pdf",
          "title": "Alabama Department of Revenue: 25f40.pdf",
          "kind": "instructions",
          "official": true,
          "quote": "Multiply total number of dependents claimed on line 1 by the amount on the dependent chart in the instructions",
          "checked": "2026-10-12"
        }
      ],
      "deductions": [
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
          "title": "2025 Form 40 Booklet (Alabama Individual Income Tax Instructions)",
          "kind": "instructions",
          "official": true,
          "quote": "$3,000",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.revenue.alabama.gov/tax-types/individual-income-tax/",
          "title": "Individual Income Tax",
          "kind": "agency_page",
          "official": true,
          "quote": "minimum personal exemptions of $1,500 for single taxpayers, $3,000 for joint filers",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40.pdf",
          "title": "Alabama Department of Revenue: 25f40.pdf",
          "kind": "instructions",
          "official": true,
          "quote": "Multiply total number of dependents claimed on line 1 by the amount on the dependent chart in the instructions",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
          "title": "2025 Form 40 booklet, Standard Deduction chart (page 9) and dependent chart",
          "kind": "instructions",
          "official": true,
          "quote": "$26,000 – $26,499 $8,325",
          "checked": "2026-10-12"
        }
      ],
      "social_security": [
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
          "title": "2025 Form 40 Booklet (Alabama Individual Income Tax Instructions)",
          "kind": "instructions",
          "official": true,
          "quote": "Income You Do Not Report",
          "checked": "2026-10-12"
        }
      ],
      "retirement_income": [
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25schrsblk.pdf",
          "title": "2025 Schedule RS (Form 40 or Form 40NR)",
          "kind": "instructions",
          "official": true,
          "quote": "each taxpayer is eligible up to $6,000 not to exceed the Retirement Income Taxable to Alabama on line 9",
          "checked": "2026-10-12"
        }
      ],
      "public_pension": [
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
          "title": "2025 Form 40 Booklet (Alabama Individual Income Tax Instructions)",
          "kind": "instructions",
          "official": true,
          "quote": "Alabama Teacher's Retirement System",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2021/12/810-3-19-.04.pdf",
          "title": "Rule 810-3-19-.04 Defined Benefit Plans",
          "kind": "agency_page",
          "official": true,
          "quote": "as defined by IRC §414(j), as amended from time to time, are exempt from Alabama income tax for an individual resident taxpayer",
          "checked": "2026-10-12"
        }
      ],
      "capital_gains": [
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
          "title": "2025 Form 40 Booklet (Alabama Individual Income Tax Instructions)",
          "kind": "instructions",
          "official": true,
          "quote": "use Schedule D to report the net gain (or loss)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
          "title": "2025 Form 40 Booklet",
          "kind": "instructions",
          "official": true,
          "quote": "Under Alabama law the entire gain is taxable, and the entire loss is deductible in the year in which it occurs.",
          "checked": "2026-10-12"
        }
      ],
      "federal_interaction": [
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
          "title": "2025 Form 40 Booklet (Alabama Individual Income Tax Instructions)",
          "kind": "instructions",
          "official": true,
          "quote": "Federal Income Tax Deduction Worksheet",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.revenue.alabama.gov/wp-content/uploads/2021/12/810-3-15-.20.pdf",
          "title": "Rule 810-3-15-.20 Federal Income Tax Deduction - Individuals",
          "kind": "agency_page",
          "official": true,
          "quote": "The imposed FIT payable for the year is the net federal income tax liability as shown due on the federal income tax return",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.revenue.alabama.gov/tax-types/individual-income-tax/",
          "title": "Individual Income Tax",
          "kind": "agency_page",
          "official": true,
          "quote": "provided deduction for federal income taxes paid by individual taxpayers",
          "checked": "2026-10-12"
        }
      ]
    },
    "unsourced": {}
  },
  "priorYearFigures": [],
  "local": {
    "onStateReturn": [],
    "separateReturns": [],
    "separateReturnsTax": 0,
    "total": 0
  },
  "taxYear": "2026",
  "methodology": "https://quantcalc.app/docs/state-tax-api/",
  "note": "State income tax only. Federal tax, FICA and local levies are not included. Social Security must be the FEDERALLY-TAXABLE portion, not gross benefits.",
  "perPerson": [
    {
      "role": "primary",
      "age": 67,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "exempt",
      "retirementExcluded": 30000,
      "retirementRule": "capped_exclusion",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 0,
      "seniorRule": "none"
    },
    {
      "role": "spouse",
      "age": 64,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "exempt",
      "retirementExcluded": 0,
      "retirementRule": "capped_exclusion",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 0,
      "seniorRule": "none"
    }
  ],
  "breakdown": {
    "taxableIncome": 33000,
    "socialSecurityInBase": 0,
    "retirementInBase": 36000,
    "conversionInBase": 0,
    "capitalGainsInBase": 5000,
    "militaryExcluded": 0,
    "retirementExcluded": 30000,
    "earnedIncomeExcluded": 0,
    "seniorSubtraction": 0,
    "militaryCredit": 0
  },
  "inputsNotSupplied": [
    {
      "input": "federalTax",
      "family": "federal_interaction",
      "assumed": "no federal income tax",
      "probed": "0%, 10%, 20% and 30% of the income supplied",
      "taxMin": 112,
      "taxMax": 1570,
      "totalTaxMin": 112,
      "totalTaxMax": 1570,
      "netTaxMin": 112,
      "netTaxMax": 1570
    }
  ],
  "notModelled": [
    {
      "id": "AL-global-767fb6d9",
      "category": "business",
      "description": "Business income rules: pass-through entity taxes, net operating losses, depreciation differences and other state additions and subtractions outside the income types listed on the API reference.",
      "lines": [
        {
          "form": "Form 40",
          "line": "9",
          "description": "Total adjustments to income (page 2 Part II line 16)"
        },
        {
          "form": "Form 40",
          "line": "17 (NOL-85A box)",
          "description": "Tax computed with a net operating loss carryover (Form NOL-85A)"
        },
        {
          "form": "Form 40 page 2 Part I",
          "line": "1",
          "description": "Alimony received"
        },
        {
          "form": "Form 40 page 2 Part I",
          "line": "2",
          "description": "Business income or loss (federal Schedule C, Alabama adjustments)"
        },
        {
          "form": "Form 40 page 2 Part I",
          "line": "5",
          "description": "Rents, royalties, partnerships, estates, trusts (Schedule E)"
        },
        {
          "form": "Form 40 page 2 Part I",
          "line": "6",
          "description": "Farm income or loss (federal Schedule F)"
        },
        {
          "form": "Form 40 page 2 Part I",
          "line": "7",
          "description": "Other income (state nature and source)"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "1a",
          "description": "Your IRA deduction"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "1b",
          "description": "Spouse's IRA deduction"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "2",
          "description": "Payments to a Keogh plan and self-employment SEP deduction"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "3",
          "description": "Penalty on early withdrawal of savings"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "4",
          "description": "Alimony paid"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "5",
          "description": "Adoption expenses"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "6",
          "description": "Moving expenses (Form 3903, Armed Forces)"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "7",
          "description": "Self-employed health insurance deduction"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "8",
          "description": "Payments to Alabama College Counts 529 / PACT"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "9",
          "description": "Health insurance deduction for small-employer employee"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "10",
          "description": "Costs to retrofit home against wind or flood"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "11",
          "description": "Deposits to a catastrophe savings account"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "12",
          "description": "Contributions to a health savings account"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "13",
          "description": "Deposits to a First-Time and Second Chance Home Buyer Savings Account"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "14",
          "description": "Firefighter's insurance premium"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "15",
          "description": "Contributions to an ABLE savings account"
        },
        {
          "form": "Form 40 page 2 Part II",
          "line": "16",
          "description": "Total adjustments → page 1 line 9"
        },
        {
          "form": "Form NOL-85 / NOL-85A",
          "line": "all",
          "description": "Net operating loss computation and carryover"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs business income or adjustment details the request does not carry.",
      "source": {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
        "quote": "If you are claiming a Net Operating"
      }
    },
    {
      "id": "AL-global-9712d4d1",
      "category": "other-state-credit",
      "description": "Other-state credits: the credits for tax paid to other states (a resident's or part-year resident's credit for income tax paid to another state, country or locality, each state's own formula) are not calculated.",
      "lines": [
        {
          "form": "Schedule CR",
          "line": "1-27",
          "description": "Credit for taxes paid to other states"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part A",
          "description": "Credit for taxes paid to other states (from Schedule CR)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs income taxed by another state or locality, which the request does not carry.",
      "source": {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
        "quote": "Credit for Taxes Paid to Another State. You must"
      }
    },
    {
      "id": "AL-global-cd7f5d31",
      "category": "itemized",
      "description": "Itemized deductions, and credits other than those each state page lists (dependent, earned-income, property-tax, renter, child and similar credits).",
      "lines": [
        {
          "form": "Form 40",
          "line": "11a",
          "description": "Itemized deductions (Schedule A line 27)"
        },
        {
          "form": "Schedule A",
          "line": "1-27",
          "description": "Itemized deductions (medical, taxes, interest, vehicle loan interest, contributions, casualty, employee expenses, other)"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part I",
          "description": "Credit for taxes paid to a foreign country"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part B",
          "description": "Alabama Enterprise Zone credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part C",
          "description": "Basic skills education credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part D",
          "description": "Rural physician credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part E",
          "description": "Coal credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part F",
          "description": "Full Employment Act of 2011 credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part G",
          "description": "Veterans Employment Act employer credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part H",
          "description": "Veterans Employment Act business start-up credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part J",
          "description": "Qualified irrigation/reservoir system credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part K",
          "description": "Accountability Act school transfer credit (Schedule AATC)"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part L",
          "description": "Accountability Act SGO credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part M",
          "description": "Adoption tax credit (Schedule AAC)"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part N",
          "description": "2013 historic rehabilitation credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part O",
          "description": "Career-technical dual enrollment credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part P",
          "description": "Investment credit (Jobs Act)"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part Q",
          "description": "Port credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part R",
          "description": "Growing Alabama credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part S",
          "description": "2017 historic rehabilitation credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part T",
          "description": "Railroad Modernization Act credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part U",
          "description": "Storm shelter credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part V",
          "description": "Volunteer emergency responders credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part W",
          "description": "Innovate Alabama credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part X",
          "description": "Volunteer first responder mileage credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part Y",
          "description": "Preceptor tax incentive credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part Z",
          "description": "Workforce housing credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part AA",
          "description": "Employer tax credit (childcare)"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part AB",
          "description": "Childcare facility credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part AC",
          "description": "Employer provider credit"
        },
        {
          "form": "Schedule OC",
          "line": "Section B Part AD",
          "description": "Income tax capital credit (KRCC-I)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs itemized deduction amounts, which the request does not carry.",
      "source": {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
        "quote": "Itemized Deductions. If you elect to itemize your"
      }
    },
    {
      "id": "AL-locality-fcbee0a3",
      "category": "locality",
      "description": "Per-worker head taxes and employer payroll taxes: Alabama occupational taxes (Birmingham), Colorado occupational privilege taxes (Denver, Aurora, Greenwood Village, Glendale, Sheridan), the Newark payroll tax, West Virginia city service fees, the Portland Arts Tax, the TriMet and Lane transit self-employment taxes, the Pennsylvania Local Services Tax: flat or employer levies, not taxes on the household's income.",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It depends on where the household lives or works: the engine covers the jurisdictions of its locality registry only.",
      "source": {
        "url": "https://www.birminghamal.gov/government/city-departments/finance/tax-license-division",
        "quote": "Lodging Tax Occupational Tax Sales Tax"
      }
    },
    {
      "id": "AL-state-3780b33b",
      "category": "other",
      "description": "Wages Alabama taxes above the federal amount (a public employee's retirement-system contributions, which are not deferred for Alabama) are not calculated: the wages input is the federal figure.",
      "lines": [
        {
          "form": "Booklet page 7 (Line 5 note)",
          "line": "State wages",
          "description": "Alabama wages above the federal amount (public employees' retirement-system contributions are not deferred for Alabama)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
        "quote": "but do not qualify for deferral on the Alabama return."
      }
    },
    {
      "id": "AL-state-8070db68",
      "category": "other",
      "description": "The exclusion of a net capital gain from exchanging precious metal bullion is not calculated: the capital-gains input does not say what was sold, so such a gain is taxed.",
      "lines": [
        {
          "form": "Act 2024-447 (booklet page 7)",
          "line": "Precious metal bullion",
          "description": "Net capital gain on the exchange of precious metal bullion excluded from 2025"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
        "quote": "Beginning January 1, 2025, any net capital gain"
      }
    },
    {
      "id": "AL-state-9a743ba5",
      "category": "other",
      "description": "Interest on United States obligations and on Alabama state and local bonds, and unemployment compensation, which Alabama exempts, and interest on other states' bonds, which Alabama taxes, are not calculated: the ordinary income input does not identify them.",
      "lines": [
        {
          "form": "Booklet page 7",
          "line": "Exempt interest and income",
          "description": "Interest on U.S. obligations and Alabama bonds, unemployment compensation (exempt), and other states' bond interest (taxable, federally exempt)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
        "quote": "Interest on obligations of the United States or any"
      }
    },
    {
      "id": "AL-state-e217cb1a",
      "category": "other",
      "description": "On separate Alabama returns of a couple filing a joint federal return, the federal tax deduction must be the share of the joint federal tax by each spouse's federal adjusted gross income; the engine deducts the federal tax it is given, so the caller must supply that share.",
      "lines": [
        {
          "form": "Booklet page 8 (Line 12 note)",
          "line": "Joint federal, separate Alabama",
          "description": "Federal tax deduction on separate Alabama returns is the joint federal tax pro-rated by each spouse's federal AGI"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
        "quote": "federal income tax liability must be determined by a ratio"
      }
    },
    {
      "id": "AL-state-e8a20556",
      "category": "part-year",
      "description": "Married couples whose residency differs (engine 1.13.0): when one spouse is a full-year resident and the other a part-year resident: Ala. Admin. Code r. 810-3-27-.01 allows a joint return only when both spouses were residents of Alabama for the tax year, and no source says whether a part-year resident is one; when both spouses are part-year residents with different resident periods: Ala. Admin. Code r. 810-3-27-.01 allows a joint return only when both spouses were residents of Alabama for the tax year, and no source says whether a part-year resident is one.",
      "lines": [
        {
          "form": "PY/NR Form 40NR",
          "line": "couples-not-modelled",
          "description": "Married couples whose residency differs: the pairs and returns not calculated (each reason on the state page)"
        }
      ],
      "couldApply": false,
      "reason": "This is a full-year resident return (no part-year or nonresident residency given).",
      "source": {
        "url": "https://admincode.legislature.state.al.us/administrative-code/810-3-27-.01",
        "quote": "A husband and wife, each having income for the tax year, may file separate returns reporting the income and deductions of each, or they may elect to file a joint return reporting their combined income and deductions."
      }
    }
  ],
  "stateDocs": "https://quantcalc.app/docs/state-tax/states/al/",
  "engineVersion": "1.14.2"
}

Every response field

Field	Type	Meaning
`state`	string	The jurisdiction's code.
`stateName`	string	The jurisdiction's name.
`tax`	number	State income tax for the year, unrounded; in Indiana and Maryland it includes the county tax (rules.localTax).
`effectiveRate`	number	tax divided by the sum of every income amount supplied; 0 when that sum is 0.
`totalTax`	number	tax plus the separate local returns (local.separateReturnsTax): every income tax the request's state and localities levy on the household for the year.
`refundableCredits`	object	The state credits paid beyond the tax (tax is before them): earned income, property-tax, renter, grocery and senior credits.
`refundableCredits.total`	number	Their total.
`refundableCredits.items`	array	One entry per credit: id, name, form, amount, valueYear (the year of the amounts used: 2025 where the 2026 figures are not published).
`refundableCredits.items[].id`	string	The credit's id.
`refundableCredits.items[].amount`	number	The credit.
`refundableCredits.projection`	string	Only with a projection beyond the rules year: the refundable credits are not projected (each uses the amounts of its valueYear).
`netTax`	number	totalTax less refundableCredits.total; negative when the refundable credits exceed every tax.
`input`	object	The request as the engine read it.
`input.filingStatus`	string	single, mfj, mfs, hoh or qss.
`input.age`	number	The primary filer's age as used (0 when not supplied).
`input.ordinaryIncome`	number	As read (0 when absent or not a number).
`input.socialSecurity`	number	As read.
`input.capitalGains`	number	As read.
`input.wages`	number	Only when supplied.
`input.iraDistributions`	number	Only when supplied.
`input.pensionPrivate`	number	Only when supplied.
`input.pensionPublic`	number	Only when supplied.
`input.pensionMilitary`	number	Only when supplied.
`input.rothConversion`	number	Only when supplied.
`input.shortTermGains`	number	Only when supplied.
`input.socialSecurityGross`	number	Only when supplied.
`input.federalTax`	number	Only when supplied.
`input.federalNiit`	number	Only when supplied.
`input.pensionPublicSsCovered`	boolean	Only when supplied.
`input.blind`	boolean	Only when supplied.
`input.disabled`	boolean	Only when supplied.
`input.spouse`	object	Only with a spouse object: the spouse's amounts as read.
`input.spouse.age`	number	The spouse's age actually used (the primary filer's when spouse.age was absent).
`input.spouse.wages`	number	As read (0 when absent).
`input.spouse.iraDistributions`	number	As read.
`input.spouse.pensionPrivate`	number	As read.
`input.spouse.pensionPublic`	number	As read.
`input.spouse.pensionMilitary`	number	As read.
`input.spouse.rothConversion`	number	As read.
`input.spouse.blind`	boolean	Only when supplied.
`input.spouse.disabled`	boolean	Only when supplied.
`input.dependents`	array	The dependents as read (each with age, student and disabled), when given.
`input.dependents[].student`	boolean	As read (false when absent).
`input.pensionFederalCivilService`	number	As read, when given.
`input.disabilityIncome`	number	As read, when given.
`input.earlyDistributions`	number	As read, when given.
`input.earlyDistributionException`	string	As read, when given.
`input.iraBasis`	number	As read, when given.
`input.survivorBenefits`	boolean	As read, when given.
`input.socialSecurityDisability`	boolean	As read, when given.
`input.priorHohQualifyingPersonDied`	boolean	As read, when given.
`rules`	object	The state's parameters as the engine applied them to this request: the bracket count, deductions, exemptions, senior subtraction and exclusion cap of its filing status (a qualifying surviving spouse: of the status the state taxes it as); partialCap and the income limits, which have only a joint and a single value, show the joint one for mfj and the single one otherwise. With the sources of each rule family that bears on the request.
`rules.taxesSocialSecurity`	boolean	Whether the state taxes any Social Security.
`rules.socialSecurityRule`	string	The Social Security rule (values below).
`rules.bracketCount`	number	Brackets in the joint schedule (mfj) or the single schedule (other statuses).
`rules.standardDeduction`	number	The joint (mfj) or single standard deduction, before 65+ additions and phase-outs.
`rules.personalExemption`	number	The joint (mfj) or single flat personal exemption (0 where the exemption is set by income tiers).
`rules.seniorSubtraction`	number	The joint (mfj) or single age subtraction.
`rules.seniorSubtractionMinAge`	number	Its age (0 = none).
`rules.capitalGainsTaxedAsOrdinary`	boolean	Whether long-term gains enter the base.
`rules.capitalGainsInclusionRatio`	number	The share of net long-term gain that enters the base (1 = all).
`rules.retirementIncomeExclusion`	object	The capped retirement exclusion.
`rules.retirementIncomeExclusion.cap`	number	Joint (mfj) or single cap at the full age.
`rules.retirementIncomeExclusion.minAge`	number	Age for the full cap or the full exclusion.
`rules.retirementIncomeExclusion.partialCap`	number	Lower cap for the younger band.
`rules.retirementIncomeExclusion.partialMinAge`	number	Age for the lower cap (0 = none).
`rules.retirementIncomeExclusion.incomeLimit`	number	Income limit (0 = none).
`rules.retirementIncomeExclusion.reducedBySocialSecurity`	boolean	Whether the cap is reduced by Social Security received.
`rules.militaryRetirement`	object	The military retirement rule (treatments below). A field that does not apply is null.
`rules.militaryRetirement.treatment`	string	The treatment (values below).
`rules.militaryRetirement.cap`	number\|null	Per-taxpayer cap; null = no dollar cap.
`rules.militaryRetirement.minAge`	number	Age splitting the two tiers (0 = one tier).
`rules.militaryRetirement.capBelowMinAge`	number\|null	Cap below that age.
`rules.militaryRetirement.percentExempt`	number\|null	Share exempt (percentage rule).
`rules.militaryRetirement.incomeLimit`	number\|null	Income limit (joint for mfj).
`rules.militaryRetirement.incomeLimitPhaseoutRange`	number\|null	Phase-out width above the limit (null = a cliff).
`rules.militaryRetirement.sharesGeneralExclusion`	boolean	Whether unexempted military pay counts as pension income for the general exclusion.
`rules.militaryRetirement.earnedIncomeBonus`	number\|null	Extra amount below the age split when own earned income exceeds the threshold.
`rules.militaryRetirement.earnedIncomeThreshold`	number\|null	That threshold.
`rules.militaryRetirement.reducedBySocialSecurity`	boolean	Whether the cap is reduced by the taxpayer's Social Security.
`rules.militaryRetirement.creditRate`	number\|null	Credit rate (credit treatment).
`rules.militaryRetirement.perTaxpayer`	boolean	Always true: the rule is applied per taxpayer.
`rules.wages`	object	The earned-income rule.
`rules.wages.treatment`	string	ordinary_income, earned_income_counts_toward_retirement_exclusion or no_income_tax.
`rules.wages.earnedIncomeInRetirementExclusion`	number\|null	Earned income per taxpayer that counts toward the retirement exclusion.
`rules.localTax`	object	The county tax included in tax.
`rules.localTax.included`	boolean	Whether a county tax is included.
`rules.localTax.rate`	number\|null	The county rate applied (localTaxRate when given).
`rules.localTax.basis`	string	How the rate was chosen (the population-weighted average, or the county rate given in localTaxRate), or none.
`rules.sources`	object	Omitted with includeSources: false. The official sources of each rule family that bears on this request, keyed by family (the anchor of that section on stateDocs, e.g. stateDocs#social_security): rates, deductions and, where the state has them, local_tax, federal_interaction, surtax and no_income_tax always; social_security with socialSecurity or socialSecurityGross; retirement_income with any pension, IRA, employer-plan, disability or Tier 2 amount; public_pension with pensionPublic or pensionFederalCivilService; military_retirement with pensionMilitary; wages with wages; roth_conversion with rothConversion; capital_gains with either gain or qualifiedDividends; senior with an age; blind_disability with blind, disabled, disabilityIncome, socialSecurityDisability true or a disabled dependent. Each value is an array of sources.
`rules.sources[].url`	string	The source document (an Internet Archive copy of the official URL where the state site refuses our checker; the title says so).
`rules.sources[].title`	string	Its title.
`rules.sources[].kind`	string	statute, instructions, agency_page, legislation, federal, regulation (official), or form, worksheet, publication, guidance, advisory, secondary.
`rules.sources[].official`	boolean	The kind counts as an official source (the docs' definition: statute, instructions, agency_page, legislation, federal, regulation).
`rules.sources[].quote`	string	A phrase or figure exactly as the source prints it, confirmed on the fetched document (the first of the source's verified claims; GET /api/state-tax/rules lists them all, each with the engine value it supports).
`rules.sources[].checked`	string	The date (YYYY-MM-DD) the quote was last confirmed on the source.
`rules.unsourced`	object	Omitted with includeSources: false. Family → the reason it has no official source, for each family in rules.sources without one (the verification page lists every such family); {} when every family is sourced.
`priorYearFigures`	array	Every amount this result used that is a prior-year figure (the state has not published the 2026 one), one entry per parameter; empty when none.
`priorYearFigures[].parameter`	string	The configuration parameter (as in GET /api/state-tax/rules).
`priorYearFigures[].rule`	string	The indexing-registry rule that sources it.
`priorYearFigures[].valueYear`	number	The year the figure is from (2025).
`priorYearFigures[].value`	number\|array	The figure used (a bracket table as rows).
`priorYearFigures[].why`	string	Why a prior-year figure is used.
`local`	object	The local income taxes of this result.
`local.onStateReturn`	array	Lines of the state return (included in tax): a county (Indiana, Maryland; without a county code the average-rate county tax), NYC, Yonkers, an Iowa school district.
`local.separateReturns`	array	Local returns filed apart from the state's (included in totalTax only).
`local.separateReturnsTax`	number	Their total.
`local.total`	number	Every local tax in this result.
`local.onStateReturn[].code`	string\|null	The jurisdiction's code (null for the average-rate county tax).
`local.onStateReturn[].name`	string	The jurisdiction.
`local.onStateReturn[].kind`	string	The local tax (a kind of research/data/state-tax-localities.json).
`local.onStateReturn[].role`	string	resident or work.
`local.onStateReturn[].form`	string	Where it is filed.
`local.onStateReturn[].base`	number	The base the rate applied to.
`local.onStateReturn[].rate`	number	The rate (the first bracket's, for a bracketed tax; a share of the state tax for Yonkers and Iowa). In a projected result, the projected year's rate (engine 1.12.1).
`local.onStateReturn[].grossTax`	number	The tax before the local credits.
`local.onStateReturn[].credits`	number	The local credits applied (at most grossTax).
`local.onStateReturn[].tax`	number	grossTax less credits.
`local.onStateReturn[].valueYear`	number	The year the jurisdiction's rate is from (an earlier year where the 2026 one is not published).
`local.onStateReturn[].rateSource`	string	Only for a rate whose one source is another city's published table.
`local.onStateReturn[].netProfitsBase`	number	Only for a net profits tax (Philadelphia, engine 1.12.1): the part of base that is self-employment income, taxed at netProfitsRate instead of rate.
`local.onStateReturn[].netProfitsRate`	number	Only with netProfitsBase: the tax year's net profits tax rate.
`local.onStateReturn[].partYear`	object	Engine 1.13.0, only for a part-year resident of the locality: residentFrom, residentTo, months (full months: more than half a month counts), proration (the factor the kind's part-year rule applied: NYC the household credit's months / 12, Yonkers the income percentage, PA EIT months / 12) and method (the form lines).
`local.onStateReturn[].partYear.residentFrom`	string	The first day lived there.
`local.onStateReturn[].partYear.residentTo`	string	The last day lived there.
`local.onStateReturn[].partYear.months`	integer	Full months lived there (more than half a month counts).
`local.onStateReturn[].partYear.proration`	number	The factor the part-year rule applied.
`local.onStateReturn[].partYear.method`	string	The form lines the part-year line follows.
`taxYear`	string	The tax year the rules are for.
`methodology`	string	This reference.
`note`	string	What tax includes, in words.
`perPerson`	array	Every response. With spouse on a joint return: the primary filer, then the spouse when the per-person model ran (spouse.age, or the primary's age, given). Otherwise one entry: role household on a joint return without spouse (the couple on one line), primary for every other return.
`perPerson[].role`	string	primary, spouse or household.
`perPerson[].age`	number	The age the rules used.
`perPerson[].militaryPay`	number	Military pay attributed to the person.
`perPerson[].militaryExcluded`	number	Military pay excluded by the military rule.
`perPerson[].militaryRule`	string	The military treatment (values below).
`perPerson[].retirementExcluded`	number	Retirement income excluded (distributions, pooled conversions and gains, public and employer pensions, non-covered pension).
`perPerson[].retirementRule`	string	The retirement rule (values below).
`perPerson[].earnedIncomeExcluded`	number	Wages inside a retirement exclusion.
`perPerson[].seniorSubtraction`	number	Age subtraction, age deduction and low-income age exemption.
`perPerson[].seniorRule`	string	age_deduction_any_income, senior_subtraction or none.
`breakdown`	object	Household totals from the engine's detail record.
`breakdown.taxableIncome`	number	State taxable income (0 when negative).
`breakdown.socialSecurityInBase`	number	Social Security entering the base.
`breakdown.retirementInBase`	number	Retirement income entering the base (including pooled conversions and gains in pool states).
`breakdown.conversionInBase`	number	Conversion entering the base separately.
`breakdown.capitalGainsInBase`	number	Long-term gain entering the base separately.
`breakdown.capitalLossDeduction`	number	The net capital loss the state let reduce other income (inside federal taxable income where the state starts there). Present only when capitalLoss is given.
`breakdown.militaryExcluded`	number	Military pay excluded.
`breakdown.retirementExcluded`	number	Retirement income excluded.
`breakdown.earnedIncomeExcluded`	number	Wages inside a retirement exclusion.
`breakdown.seniorSubtraction`	number	Age subtractions and deductions.
`breakdown.militaryCredit`	number	Military retirement credit (before the credit floor).
`breakdown.combinedSeparateReturn`	object	Present only when two separate columns on one form (Delaware filing status 4) cost less than the joint return; tax is then their sum and the other breakdown lines are the joint return's.
`breakdown.combinedSeparateReturn.jointTax`	number	The joint return's tax.
`breakdown.combinedSeparateReturn.filerTax`	number	The filer's column.
`breakdown.combinedSeparateReturn.spouseTax`	number	The spouse's column.
`stateDocs`	string	This state's documentation page.
`engineVersion`	string	The engine release.
`error`	string	400 responses only: the message (listed below).
`input.spouse.railroadRetirementTier2`	number	As read, when given.
`input.spouse.railroadRetirementTier1`	number	As read, when given.
`input.spouse.employerPlanDistributions`	number	As read, when given.
`input.spouse.planMinimumRetirementAge`	integer	Only when supplied (joint returns).
`input.spouse.deceasedSpouseAge`	integer	Only when supplied (joint returns).
`input.spouse.socialSecuritySurvivor`	boolean	As read, when given (joint returns).
`input.spouse.selfEmploymentIncome`	number	As read, when given.
`input.railroadRetirementTier2`	number	As read, when given.
`input.railroadRetirementTier1`	number	As read, when given.
`input.employerPlanDistributions`	number	As read, when given.
`input.qualifiedDividends`	number	As read, when given.
`input.localTaxRate`	number	As read, when given.
`input.localities`	array	Only when supplied: each locality as read, {code, role, wages (a workplace)}.
`input.otherLocalTaxCredit`	number	Only when supplied.
`input.localUnearnedIncome`	number	Only when supplied.
`input.propertyTaxPaid`	number\|boolean	Only when supplied.
`input.rentPaid`	number\|boolean	Only when supplied.
`input.rentIncludesHeat`	number\|boolean	Only when supplied.
`input.homeValue`	number\|boolean	Only when supplied.
`input.taxExemptInterest`	number\|boolean	Only when supplied.
`input.medicalExpenses`	number\|boolean	Only when supplied.
`breakdown.railroadExcluded`	number	Railroad Retirement benefits kept out of the base: Tier 2 and the taxable share of Tier 1. Present only when railroadRetirementTier2 or railroadRetirementTier1 is given.
`breakdown.qualifiedDividendsExcluded`	number	Qualified dividends excluded by the state (0 where it has no exclusion). Present only when qualifiedDividends is given.
`input.federalTaxBeforeCredits`	number	Only when supplied.
`input.planMinimumRetirementAge`	integer	Only when supplied.
`input.deceasedSpouseAge`	integer	Only when supplied.
`input.socialSecuritySurvivor`	boolean	As read, when given.
`input.federalRefundableCredits`	number	Only when supplied.
`federal`	object	The federal return computeFederal built (present only with computeFederal: true).
`federal.engineVersion`	string	The federal engine version.
`federal.taxYear`	integer	The federal tax year (the engine's parameters).
`federal.inputs`	object	The federal return's inputs, mapped from the request (the federal API's field names).
`federal.inputs.filingStatus`	string	single, mfj, mfs, hoh or qss.
`federal.inputs.age`	integer	The primary filer's age.
`federal.inputs.spouseAge`	integer	The spouse's age (joint returns).
`federal.inputs.blindCount`	integer	How many are blind (the filer, and the spouse on a joint return): present only when 1 or 2.
`federal.inputs.iraDistributions`	number	iraDistributions plus employerPlanDistributions, both spouses.
`federal.inputs.rothConversion`	number	rothConversion, both spouses.
`federal.inputs.pension`	number	Private, public, military and federal civil service pensions and Railroad Retirement Tier 2, both spouses.
`federal.inputs.shortTermGains`	number	shortTermGains.
`federal.inputs.longTermGains`	number	capitalGains; with capitalLoss, minus (capitalLoss less capitalLossCarryover): the year's own net loss, on Schedule D line 15.
`federal.inputs.capitalLossCarryoverLongTerm`	number	capitalLossCarryover, as the Schedule D line 14 carryover: present only when not 0.
`federal.inputs.socialSecurityGross`	number	socialSecurityGross.
`federal.inputs.taxableInterest`	number	ordinaryIncome (interest, non-qualified dividends), as Form 1040 line 2b: present only when not 0.
`federal.inputs.ordinaryDividends`	number	qualifiedDividends, as Form 1040 line 3b: present only when not 0.
`federal.inputs.qualifiedDividends`	number	qualifiedDividends, as Form 1040 line 3a (the capital-gains worksheet): present only when not 0.
`federal.inputs.wages`	number	wages (the filer's; the household's without spouse), as W-2 box 1 = box 3 (at most the wage base) = box 5: present only when not 0.
`federal.inputs.socialSecurityWithheld`	number	The employer's social security withholding on wages (W-2 box 4, on box 3): present with wages.
`federal.inputs.medicareTaxWithheld`	number	The employer's Medicare withholding on wages (W-2 box 6, with the additional Medicare withholding): present with wages.
`federal.inputs.selfEmploymentIncome`	number	selfEmploymentIncome, as the filer's Schedule C net profit: present only when not 0.
`federal.inputs.spouseWages`	number	spouse.wages on a joint return, as the spouse's W-2: present only when not 0.
`federal.inputs.spouseSocialSecurityWithheld`	number	The spouse's employer social security withholding: present with spouseWages.
`federal.inputs.spouseMedicareTaxWithheld`	number	The spouse's employer Medicare withholding: present with spouseWages.
`federal.inputs.spouseSelfEmploymentIncome`	number	spouse.selfEmploymentIncome on a joint return, as the spouse's Schedule C net profit: present only when not 0.
`federal.toState`	object	The values handed to the state engine.
`federal.toState.socialSecurity`	number	The federally taxable Social Security (Form 1040 line 6b).
`federal.toState.federalTax`	number	The federal income tax without the NIIT (Form 1040 line 22: no credits are modelled).
`federal.toState.federalNiit`	number	The net investment income tax.
`federal.toState.federalTaxBeforeCredits`	number	The same as federalTax (no credits are modelled).
`federal.toState.federalRefundableCredits`	number	Zero (no credits are modelled).
`federal.toState.federalTaxableOrdinaryIncome`	number	The ordinary part of federal taxable income, read by the states whose base starts from federal taxable income.
`federal.toState.federalTaxableLongTermGain`	number	The long-term gain part of federal taxable income.
`federal.toState.earnedIncome`	number	With self-employment income: the filer's earned income the state engine received, wages plus the net profit less half the filer's self-employment tax. Present only when selfEmploymentIncome is given and not 0 (either spouse).
`federal.toState.spouseEarnedIncome`	number	The same for the spouse on a joint return.
`federal.result`	object	The federal result, in the shape POST /api/federal-tax returns it (see /docs/federal-tax/api/).
`federal.schedules`	object	With wages or selfEmploymentIncome: the federal return's schedules as POST /api/federal-tax reports them (work: Schedule SE, the self-employment tax deduction, Form 8959; qbi: the qualified business income deduction; and the others). federal.result.totalTax then includes the self-employment tax and the Additional Medicare Tax (Schedule 2); federal.toState.federalTax stays the income tax.
`federal.lines`	array	The federal return's Form 1040 lines, in the shape POST /api/federal-tax returns them.
`federal.docs`	string	The federal engine documentation.
`input.capitalLoss`	number	As read, when given.
`input.capitalLossCarryover`	number	As read, when given.
`input.selfEmploymentIncome`	number	As read, when given.
`rulesYear`	integer	With projection only (engine 1.10.0): the tax year whose rules were projected (2026).
`projectedYear`	integer	With projection only: the tax year estimated (projection.year).
`projected`	boolean	With projection only: true when projectedYear is after the rules year (the result is an estimate on the rules year's rules); false for projection.year 2026.
`inputsNotSupplied`	array	Every response unless includeInputsNotSupplied is false (engine 1.10.0): the facts and splits the request did not give that could change this result, each probed (empty = no probe changed the tax).
`inputsNotSupplied[].input`	string	The request key, as a caller supplies it (spouse.age for the spouse's).
`inputsNotSupplied[].family`	string	The rule family it belongs to (the keys of rules.sources).
`inputsNotSupplied[].assumed`	string	What the engine used without it.
`inputsNotSupplied[].probed`	string	The probe values, in words.
`inputsNotSupplied[].taxMin`	number	The lowest tax over the probes and the result as given.
`inputsNotSupplied[].taxMax`	number	The highest tax over the probes and the result as given.
`inputsNotSupplied[].totalTaxMin`	number	The lowest totalTax among the probes and this result (engine 1.12.0: a probe can move only the separate local returns).
`inputsNotSupplied[].totalTaxMax`	number	The highest.
`inputsNotSupplied[].netTaxMin`	number	The lowest netTax among the probes and this result (engine 1.12.0: a probe can also move only the refundable credits).
`inputsNotSupplied[].netTaxMax`	number	The highest.
`notModelled`	array	Every response unless includeNotModelled is false (engine 1.12.0): the parts of the request's state's income tax law the engine does not model, from the state's form map and not-calculated list (empty for a state without an income tax). The other half of inputsNotSupplied: that lists facts the engine reads but was not given; this lists rules the engine does not have.
`notModelled[].id`	string	A stable identifier: the state, the list it comes from and a hash of its text.
`notModelled[].category`	string	payments, tax-table, other-state-credit, part-year, amt, dependent-care, itemized, business, locality or other.
`notModelled[].description`	string	What is not modelled, in words.
`notModelled[].lines`	array	The state form lines that carry it (form, line, description); empty for an item of the state's list with no single line.
`notModelled[].lines[].form`	string	The form or schedule.
`notModelled[].lines[].line`	string	The line.
`notModelled[].lines[].description`	string	What the line is.
`notModelled[].couldApply`	boolean\|string	Whether it can bear on this request: true, false or "unknown" (it turns on facts the request does not carry). A part-year item is true only on a part-year or nonresident return; a dependent-care item is false when dependents is []; payments and penalties are false; a tax-table difference is true.
`notModelled[].reason`	string	Why couldApply is what it is.
`notModelled[].source`	object	Unless includeSources is false (and not in the library's no-sources build): the official document and a verbatim phrase from it.
`notModelled[].source.url`	string	The official document.
`notModelled[].source.quote`	string	A verbatim phrase from it.
`projection`	object	Projected responses only (engine 1.10.0): how the result was projected.
`projection.rulesYear`	integer	The rules year (2026).
`projection.projectedYear`	integer	The tax year estimated.
`projection.cpiFactor`	number	The cumulative CPI factor used (from inflation, or as given).
`projection.indexing`	string	The mode that ran: "law" or "inflation" (see the request field).
`projection.inflation`	number	The annual rate, when the request gave inflation.
`projection.parameters`	array	Every amount of the state's rules that bears on this result (setting it to zero or far above its value would change the tax), in registry order. Engine 1.12.1: with localities, also each local amount that bears on the result, named local.<locality code>.<amount> (rate, rateNonresident, schoolIncomeTaxRate, netProfitsRate, thresholdSingle, thresholdJoint, exemption, lowIncomeExemption, seniorCredit, zeroBelow), with its rule local.<kind>.
`projection.parameters[].parameter`	string	The engine configuration field (a brackets_* field is a rate schedule's thresholds).
`projection.parameters[].rule`	string	The registry rule that moves it (a key of projection.rules).
`projection.parameters[].method`	string	cpi, federal, fixed, scheduled, birth_year, age, derived or unknown; with indexing "inflation": inflation (multiplied by the factor), held, or birth_year.
`projection.parameters[].lawMethod`	string	indexing "inflation" only: how the law would move this amount (the rule's method).
`projection.parameters[].rulesYearValue`	number\|array	The rules year's value: a number, an array, or a rate schedule [[from, to (null = no top), rate], ...].
`projection.parameters[].projectedValue`	number\|array	The value used for the projected year, in the same shape.
`projection.parameters[].multiplier`	number	cpi and federal, and a scheduled amount indexed after its schedule: the factor applied to the increase.
`projection.parameters[].valueYear`	integer	cpi and federal, when the engine carries an earlier year's figure: that year (the multiplier includes the years since).
`projection.parameters[].scheduleYear`	integer\|null	scheduled: the scheduled year whose value applies (null before the first). A local amount with published years (Metro's thresholds) carries it too.
`projection.parameters[].afterSchedule`	boolean	scheduled: true when the projected year is past the last scheduled year.
`projection.parameters[].ageShift`	integer	birth_year: the years added to the age test.
`projection.codeTables`	array	The state's dollar tables held in code (every one, bearing or not), with their rule and method. Engine 1.12.1: with localities, also each locality's rate schedules and credit tables (local.<code>.tables), fixed.
`projection.codeTables[].table`	string	The table's registry id.
`projection.codeTables[].rule`	string	Its rule.
`projection.codeTables[].method`	string	Its method (fixed for every table the engine holds in code).
`projection.rules`	object	Rule id -> the rule of every parameter and code table listed.
`projection.rules{}.method`	string	The rule's method.
`projection.rules{}.index`	string	cpi and federal: the index or federal amount the statute names.
`projection.rules{}.rounding`	object	cpi and federal (and a schedule indexed after it): how the increase is rounded.
`projection.rules{}.rounding.mode`	string	nearest, down, up or none.
`projection.rules{}.rounding.step`	number	The multiple rounded to (0 with none).
`projection.rules{}.afterSchedule`	string	scheduled: fixed, cpi or federal after the last scheduled year.
`projection.rules{}.scheduleValueYear`	integer	scheduled, when present: the scheduled values are that year's dollars and are indexed from it (the afterSchedule way) in every scheduled year too, not only after the last (Maine's standard deduction: from 2027 the federal one, scheduled at its 2026 amount).
`projection.rules{}.birthYear`	integer	birth_year: the cutoff birth year.
`projection.rules{}.derivedFrom`	string	derived: the parameter this amount is defined from (the statute's ratio times that amount as projected, rounded the rule's way).
`projection.rules{}.ratio`	number	derived: the statute's ratio.
`projection.rules{}.establishes`	string	What the law says about these amounts. Provenance: omitted with includeSources: false (and by a library built without sources).
`projection.rules{}.sources`	array	Omitted with includeSources: false: the official sources, each with url, title, kind, official, quote and checked (as rules.sources).
`projection.notApplied`	string[]	What the projection does not do, in words (rates and rules stay the rules year's; the factor stands in for every index; below a factor of 1, no floor).
`projection.enactedChangesNotApplied`	array	Changes the state enacted for later years that the projection does not apply (in every build; only their sources are omitted with includeSources: false).
`projection.enactedChangesNotApplied[].what`	string	The change, in words.
`projection.enactedChangesNotApplied[].years`	string	The years it applies to.
`projection.enactedChangesNotApplied[].conditional`	boolean	true when it depends on a revenue trigger or another future event.
`projection.enactedChangesNotApplied[].rule`	string	indexing "inflation" only, on the entries it adds: the scheduled rule of the registry whose schedule this mode does not apply.
`projection.enactedChangesNotApplied[].sources`	array	Omitted with includeSources: false: its sources, as above.
`projection.rules{}.heldTopBoundaries`	integer	Bracket tables: the number of top boundaries between rows the statute fixes (held; the others are indexed), when not 0 (Oregon's top threshold).
`projection.rules{}.settledUntil`	integer	A local rule (local.<kind>, engine 1.12.1): the last tax year the law settles its amounts; a later year is refused.
`residency`	object	Only with residency: how the return was figured.
`residency.status`	string	resident, partYear or nonresident: the residency of the return the breakdown describes (a couple: the applied option's main return, residency.couple.breakdownIs).
`residency.method`	string	resident; R (the full-year tax × the ratio), D (the tax on the state's own income, items prorated), C (the full-year tax less a nonresident credit), S (the tax on the state's own income, nothing prorated) or none (no tax).
`residency.methodText`	string	The method in words.
`residency.form`	string	The state's form for this return.
`residency.fullYearTax`	number	The tax a full-year resident would owe on all the year's income (the earned income credits left out).
`residency.numerator`	number	The ratio's numerator: the state's own income measure (days or months for a days / months proration).
`residency.denominator`	number	The ratio's denominator: the whole year's (365 days, 12 months).
`residency.ratio`	number	The ratio as the form rounds and bounds it (C: 1 less the nonresident share).
`residency.ratioDecimals`	integer\|null	Its places; null where the form states no rounding.
`residency.ratioLongTermGains`	number	Montana: the net long-term capital gains ratio.
`residency.proration`	number	The factor the prorated items were scaled by (D), or the factor of a special line (CA's deduction percentage, MD 505 line 15).
`residency.prorationBasis`	string	income, days, months or none.
`residency.days`	integer	Days resident (a days proration).
`residency.months`	integer	Months resident (NJ: 15 days or more is a month; MD's pension exclusion).
`residency.incomePercentage`	number	Virginia 760PY: the standard deduction's income percentage.
`residency.nonresidentShare`	number	C: the share of the tax credited.
`residency.stateTaxableIncome`	number	CA, MD 505, VA 763: the state's taxable income on this return.
`residency.specialNonresidentTax`	number	Maryland 505NR line 17: the special nonresident tax on Maryland taxable income (in place of a county tax).
`residency.retirementExclusionShare`	number	DE, ME: the share of the retirement exclusion in the state's own income.
`residency.notModelled`	string[]	What this return leaves out (the earned income credits; Indiana's county tax where it does not apply). The state's general list, with the part-year items marked couldApply true on this return, is the top-level notModelled.
`residency.couple`	object	Engine 1.13.0, only with residency.spouse: the state's rule for the couple and every treatment it allows, computed.
`residency.couple.pair`	string	RP (one spouse a full-year resident, the other part-year), RN (full-year resident and nonresident), PN (part-year and nonresident), PP (both part-year, different periods), NN1 (both nonresidents, only one with income from the state) or same (the same residency: one joint return).
`residency.couple.rule`	string	The state's rule for the pair in words (quoted from its instructions in rules.sources, family residency).
`residency.couple.condition`	string	Engine 1.14.0: the condition of the couple's own facts that set the treatments (Massachusetts' filing-requirement and threshold exceptions, Vermont's TB-55 options, Virginia's Form 763 status); absent when none applies.
`residency.couple.note`	string	Engine 1.14.0: what the state's documents leave open about this pair (for example, that they describe one treatment without saying whether another is allowed); absent when nothing.
`residency.couple.options`	array	One entry per treatment the state allows: joint (one joint part-year / nonresident return), separate (each spouse's own return) or jointAsResidents (a joint resident return).
`input.residency`	object	Only when supplied: the status, the resident period as days of the year (residentFromDay, residentToDay) and stateIncome as read.
`input.residency.status`	string	As read.
`input.residency.residentFromDay`	integer	residentFrom as a day of the tax year (1-365), when given.
`input.residency.residentToDay`	integer	residentTo as a day of the tax year, when given.
`input.residency.stateIncome`	object	The stateIncome amounts as read.
`input.residency.spouse`	object	Only when supplied: the spouse's status, resident period (residentFromDay, residentToDay) and stateIncome as read.
`input.residency.spouseShare`	object	Only when supplied: the spouse's parts of the household amounts as read.
`input.residency.election`	string	Only when supplied: the election as read.
`residency.couple.options[].treatment`	string	joint, separate or jointAsResidents.
`residency.couple.options[].tax`	number	Only when computed: the option's state tax (both returns for separate).
`residency.couple.options[].totalTax`	number	Only when computed: with the separate local returns.
`residency.couple.options[].netTax`	number	Only when computed: totalTax less the refundable credits.
`residency.couple.options[].notComputed`	string	Only when not computed: why (the state's instructions leave it unsettled, a computation the engine does not model, or the inputs it needs).
`residency.couple.options[].returns`	array	Only when computed: the option's returns (one joint, or each spouse's).
`residency.couple.options[].returns[].return`	string	joint, primary or spouse.
`residency.couple.options[].returns[].filingStatus`	string	mfj (a joint return) or mfs (a spouse's separate return).
`residency.couple.options[].returns[].residency`	string	resident, partYear or nonresident: the return's own.
`residency.couple.options[].returns[].method`	string	resident, or the state's part-year / nonresident method (R, D, C, S, none).
`residency.couple.options[].returns[].form`	string	Only on a part-year / nonresident return: its form.
`residency.couple.options[].returns[].filed`	boolean	false: no return (no income the state taxes).
`residency.couple.options[].returns[].tax`	number	The return's tax.
`residency.couple.options[].returns[].netTax`	number	The return's tax with its separate local returns, less its refundable credits.
`residency.couple.options[].returns[].taxableIncome`	number	The return's taxable income.
`residency.couple.options[].returns[].ratio`	number	Only with an apportionment ratio: the ratio as the form rounds it.
`residency.couple.applied`	string	The treatment in tax: joint, separate or jointAsResidents.
`residency.couple.appliedBecause`	string	Why: required (the only one allowed), the state's default absent an election, residency.election, or a free choice where the request's mfj names a joint return.
`residency.couple.lowest`	string\|null	The computed option with the lowest netTax; null when fewer than two are computed or the lowest is shared.
`residency.couple.breakdownIs`	string	Which return the breakdown, perPerson and residency method describe: the joint return, the primary's separate return or the joint resident return.
`local.separateReturns[].partYear`	object	The same, for a separate local return (PA EIT, an Ohio school district).
`breakdown.rentalLossDeduction`	number	The rental loss the state let reduce other income (0 in PA and NJ). Present only when rentalNetIncome is given.
`input.rentalNetIncome`	number	As read, when given.

Sources in the response

rules.sources cites, for every rule family that bears on the request, the official sources the engine's rule follows: the document's URL and title, its kind, a phrase or figure exactly as the source prints it, and the date that quote was last confirmed on the source. The keys are the section anchors of the state's page (stateDocs#social_security and so on), where each rule is explained in full. A family with no official source is named in rules.unsourced with the reason. The citations are compiled into the engine from the same research file as these pages (provenance JSON), so the API, the library and the documentation cite the same sources; "includeSources": false leaves both blocks out. From the response above:

{
  "sources": {
    "rates": [
      {
        "url": "https://www.revenue.alabama.gov/tax-types/individual-income-tax/",
        "title": "Individual Income Tax",
        "kind": "agency_page",
        "official": true,
        "quote": "2 percent on first $500 of taxable income",
        "checked": "2026-10-12"
      },
      {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
        "title": "Alabama Department of Revenue: 25f40bk.pdf",
        "kind": "instructions",
        "official": true,
        "quote": "Amount on Page 1, Line 10 Dependent Exemption 0 - 50,000 50,001 - 100,000 Over 100,000 1,000 500 300",
        "checked": "2026-10-12"
      },
      {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40.pdf",
        "title": "Alabama Department of Revenue: 25f40.pdf",
        "kind": "instructions",
        "official": true,
        "quote": "Multiply total number of dependents claimed on line 1 by the amount on the dependent chart in the instructions",
        "checked": "2026-10-12"
      }
    ],
    "deductions": [
      {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
        "title": "2025 Form 40 Booklet (Alabama Individual Income Tax Instructions)",
        "kind": "instructions",
        "official": true,
        "quote": "$3,000",
        "checked": "2026-10-12"
      },
      {
        "url": "https://www.revenue.alabama.gov/tax-types/individual-income-tax/",
        "title": "Individual Income Tax",
        "kind": "agency_page",
        "official": true,
        "quote": "minimum personal exemptions of $1,500 for single taxpayers, $3,000 for joint filers",
        "checked": "2026-10-12"
      },
      {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40.pdf",
        "title": "Alabama Department of Revenue: 25f40.pdf",
        "kind": "instructions",
        "official": true,
        "quote": "Multiply total number of dependents claimed on line 1 by the amount on the dependent chart in the instructions",
        "checked": "2026-10-12"
      },
      {
        "url": "https://www.revenue.alabama.gov/wp-content/uploads/2026/01/25f40bk.pdf",
        "title": "2025 Form 40 booklet, Standard Deduction chart (page 9) and dependent chart",
        "kind": "instructions",
        "official": true,
        "quote": "$26,000 – $26,499 $8,325",
        "checked": "2026-10-12"
      }
    ]
  },
  "unsourced": {}
}

String values

Value set	Where it appears	Values
`socialSecurityRule`	rules.socialSecurityRule	`exempt`, `full_above_threshold`, `federal_conformity`, `capped_25_percent`, `stepped_subtraction`, `ratable_phaseout`, `credit_phaseout`, `age_and_agi_test`, `age_banded_subtraction`
`militaryRetirement.treatment`	rules.militaryRetirement.treatment and perPerson[].militaryRule	`no_income_tax`, `taxable_as_pension`, `exempt`, `capped_exclusion`, `percentage_exclusion`, `credit`
`retirementRule`	perPerson[].retirementRule	`co_pension_and_ss_subtraction`, `full_exclusion_age_gated`, `full_exclusion`, `agi_phasedown_exclusion`, `age_deduction_any_income`, `pooled_retirement_and_investment_exclusion`, `pension_only_capped_exclusion`, `capped_exclusion`, `public_or_employer_pension_exemption`, `none`
`seniorRule`	perPerson[].seniorRule	`age_deduction_any_income`, `senior_subtraction`, `none`

Social Security rules

socialSecurityRule	Jurisdictions
`exempt`	34 taxing jurisdictions, plus the 9 with no income tax
`age_banded_subtraction`	CO
`credit_phaseout`	UT
`capped_25_percent`	CT
`stepped_subtraction`	MN
`federal_conformity`	MT
`full_above_threshold`	NM
`age_and_agi_test`	RI
`ratable_phaseout`	VT

Military retirement treatments

militaryRetirement.treatment	Jurisdictions
`no_income_tax`	AK, FL, NV, NH, SD, TN, TX, WA, WY
`exempt`	AZ, IL, IN, MA, MI, NC, PA, AL, AR, CT, HI, IA, KS, LA, ME, MN, MS, MO, NE, NJ, NY, ND, OH, OK, RI, SC, VT, WV, WI
`capped_exclusion`	CO, ID, CA, DE, GA, MD, NM, VA
`taxable_as_pension`	KY, MT, OR, DC
`credit`	UT

Worked examples

Each request below was run through the engine when these pages were generated; the responses are its output, unedited.

A couple with mixed income (Georgia)

Each spouse has their own amounts: the primary a traditional IRA and a public pension, the spouse wages and a 401(k) (employerPlanDistributions). Interest, qualified dividends, long-term gains and Social Security are household totals at the top level. Georgia gives each spouse their own retirement exclusion, with its cap set by that spouse's age, and counts part of a spouse's wages toward it: perPerson shows each spouse's exclusion and the rule that gave it, rules.retirementIncomeExclusion the caps and rules.sources the Georgia documents behind them.

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "GA",
  "filingStatus": "mfj",
  "age": 67,
  "iraDistributions": 30000,
  "pensionPublic": 22000,
  "ordinaryIncome": 4000,
  "qualifiedDividends": 6000,
  "capitalGains": 12000,
  "socialSecurity": 27200,
  "socialSecurityGross": 32000,
  "spouse": {
    "age": 63,
    "wages": 48000,
    "employerPlanDistributions": 15000
  }
}

Returns tax $648.70 (effective rate 0.3951%), engine version 1.14.2.

The complete response

{
  "state": "GA",
  "stateName": "Georgia",
  "tax": 648.7,
  "effectiveRate": 0.003950669914738124,
  "totalTax": 648.7,
  "refundableCredits": {
    "total": 0,
    "items": []
  },
  "netTax": 648.7,
  "input": {
    "filingStatus": "mfj",
    "age": 67,
    "ordinaryIncome": 4000,
    "socialSecurity": 27200,
    "capitalGains": 12000,
    "wages": 0,
    "iraDistributions": 30000,
    "pensionPublic": 22000,
    "socialSecurityGross": 32000,
    "qualifiedDividends": 6000,
    "spouse": {
      "age": 63,
      "wages": 48000,
      "iraDistributions": 0,
      "pensionPrivate": 0,
      "pensionPublic": 0,
      "pensionMilitary": 0,
      "rothConversion": 0,
      "employerPlanDistributions": 15000
    }
  },
  "rules": {
    "taxesSocialSecurity": false,
    "socialSecurityRule": "exempt",
    "bracketCount": 1,
    "standardDeduction": 30000,
    "personalExemption": 0,
    "seniorSubtraction": 0,
    "seniorSubtractionMinAge": 0,
    "capitalGainsTaxedAsOrdinary": true,
    "capitalGainsInclusionRatio": 1,
    "retirementIncomeExclusion": {
      "cap": 130000,
      "minAge": 65,
      "partialCap": 70000,
      "partialMinAge": 62,
      "incomeLimit": 0,
      "reducedBySocialSecurity": false
    },
    "militaryRetirement": {
      "treatment": "capped_exclusion",
      "cap": 0,
      "minAge": 62,
      "capBelowMinAge": 17500,
      "percentExempt": null,
      "incomeLimit": null,
      "incomeLimitPhaseoutRange": null,
      "sharesGeneralExclusion": true,
      "earnedIncomeBonus": 17500,
      "earnedIncomeThreshold": 17500,
      "reducedBySocialSecurity": false,
      "creditRate": null,
      "perTaxpayer": true
    },
    "wages": {
      "treatment": "earned_income_counts_toward_retirement_exclusion",
      "earnedIncomeInRetirementExclusion": 5000
    },
    "localTax": {
      "included": false,
      "rate": null,
      "basis": "none"
    },
    "sources": {
      "rates": [
        {
          "url": "https://www.legis.ga.gov/api/legislation/document/20252026/249080",
          "title": "HB 463 (As Passed House and Senate), Georgia Economic Growth and Tax Relief Act of 2026",
          "kind": "legislation",
          "official": true,
          "quote": "shall be 5.19 percent 4.99 percent",
          "checked": "2026-10-12"
        },
        {
          "url": "https://dor.georgia.gov/document/document/2026-employers-tax-guide-updated-september-2026/download",
          "title": "Employer's Withholding Tax Guide 2026 (revised)",
          "kind": "instructions",
          "official": true,
          "quote": "flat rate of 4.99%",
          "checked": "2026-10-12"
        },
        {
          "url": "https://gov.georgia.gov/press-releases/2026-05-11/gov-kemp-signs-legislation-lowering-taxes-and-supporting-economic-growth",
          "title": "Gov. Kemp Signs Legislation Lowering Taxes and Supporting Economic Growth (2026-05-11)",
          "kind": "legislation",
          "official": true,
          "quote": "lowers Georgia's state income tax rate from 5.19% to 4.99%, beginning January 1, 2026",
          "checked": "2026-10-12"
        }
      ],
      "deductions": [
        {
          "url": "https://dor.georgia.gov/document/document/2026-employers-tax-guide-updated-september-2026/download",
          "title": "Employer's Withholding Tax Guide 2026 (revised)",
          "kind": "instructions",
          "official": true,
          "quote": "$15,000 for Single, Head of Household",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.legis.ga.gov/api/legislation/document/20252026/249080",
          "title": "HB 463 (As Passed House and Senate), Georgia Economic Growth and Tax Relief Act of 2026",
          "kind": "legislation",
          "official": true,
          "quote": "separate return, $12,000.00 $15,000.00",
          "checked": "2026-10-12"
        },
        {
          "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
          "title": "2025 IT-511 Individual Income Tax Instruction Booklet",
          "kind": "instructions",
          "official": true,
          "quote": "Married filing jointly $24,000 Single $12,000",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/2026id_/https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
          "title": "2025 IT-511 Individual Income Tax Booklet (archived copy)",
          "kind": "instructions",
          "official": true,
          "quote": "Federal adjusted gross income is less than $20,000",
          "checked": "2026-09-27"
        },
        {
          "url": "https://dor.georgia.gov/qualifying-child-credit",
          "title": "Georgia Department of Revenue: qualifying-child-credit",
          "kind": "agency_page",
          "official": true,
          "quote": "provides an income tax credit of $250 for each qualifying child",
          "checked": "2026-10-12"
        },
        {
          "url": "https://dor.georgia.gov/low-income-tax-credit",
          "title": "Georgia Department of Revenue: low-income-tax-credit",
          "kind": "agency_page",
          "official": true,
          "quote": "Federal adjusted gross income is less than $20,000",
          "checked": "2026-10-12"
        }
      ],
      "social_security": [
        {
          "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
          "title": "2025 IT-511 Individual Income Tax Instruction Booklet",
          "kind": "instructions",
          "official": true,
          "quote": "Social Security or Railroad Retirement (Tier 1 and Tier 2)",
          "checked": "2026-10-12"
        }
      ],
      "retirement_income": [
        {
          "url": "https://www.legis.ga.gov/api/legislation/document/20252026/249080",
          "title": "HB 463 (As Passed House and Senate), Georgia Economic Growth and Tax Relief Act of 2026",
          "kind": "legislation",
          "official": true,
          "quote": "before December 31, 2026, retirement income from any source",
          "checked": "2026-10-12"
        },
        {
          "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
          "title": "2025 IT-511 Individual Income Tax Instruction Booklet",
          "kind": "instructions",
          "official": true,
          "quote": "If age 62-64 or less than age 62 and permanently disabled enter $35,000, or if age 65 or older enter $65,000",
          "checked": "2026-10-12"
        },
        {
          "url": "https://dor.georgia.gov/retirement-income-exclusion",
          "title": "Retirement Income Exclusion",
          "kind": "agency_page",
          "official": true,
          "quote": "Taxpayers who are 62 or older",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/2026id_/https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
          "title": "2025 IT-511 Individual Income Tax Booklet (archived copy)",
          "kind": "instructions",
          "official": true,
          "quote": "Capital Gains (Losses)",
          "checked": "2026-09-27"
        },
        {
          "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
          "title": "2025 IT-511 booklet (Schedule 1 retirement income exclusion)",
          "kind": "instructions",
          "official": true,
          "quote": "Ln 6 Interest Ln 7 Dividend Ln 8 Alimony Ln 9 Capital Gains Ln 10 Other Income",
          "checked": "2026-10-12"
        }
      ],
      "public_pension": [
        {
          "url": "https://dor.georgia.gov/retirement-income-exclusion",
          "title": "Retirement Income Exclusion",
          "kind": "agency_page",
          "official": true,
          "quote": "Income from pensions and annuities",
          "checked": "2026-10-12"
        }
      ],
      "wages": [
        {
          "url": "https://web.archive.org/web/2026id_/https://dor.georgia.gov/retirement-income-exclusion",
          "title": "Retirement income exclusion",
          "kind": "agency_page",
          "official": true,
          "quote": "Up to $5,000 of earned income",
          "checked": "2026-09-27"
        },
        {
          "url": "https://web.archive.org/web/2026id_/https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
          "title": "2025 it 511 individual income tax booklet",
          "kind": "agency_page",
          "official": true,
          "quote": "allowable exclusion may be earned income. See",
          "checked": "2026-09-27"
        }
      ],
      "capital_gains": [
        {
          "url": "https://www.legis.ga.gov/api/legislation/document/20252026/249080",
          "title": "HB 463 (As Passed House and Senate), Georgia Economic Growth and Tax Relief Act of 2026",
          "kind": "legislation",
          "official": true,
          "quote": "Georgia taxable net income of an individual shall be the taxpayer's federal adjusted",
          "checked": "2026-10-12"
        },
        {
          "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
          "title": "2025 IT-511 Individual Income Tax Instruction Booklet",
          "kind": "instructions",
          "official": true,
          "quote": "Capital Gains (Losses)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
          "title": "2025 IT-511 Individual Income Tax Booklet",
          "kind": "instructions",
          "official": true,
          "quote": "Enter Federal adjusted gross income from Form 1040.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
          "title": "2025 IT-511 Individual Income Tax Booklet",
          "kind": "instructions",
          "official": true,
          "quote": "Income or losses should be allocated to the person who owns the item.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.irs.gov/pub/irs-pdf/f1040sd.pdf",
          "title": "2025 Schedule D (Form 1040), Capital Gains and Losses",
          "kind": "federal",
          "official": true,
          "quote": "If line 16 is a loss, enter here and on Form 1040, 1040-SR, or 1040-NR, line 7a, the smaller of: • The loss on line 16; or • ($3,000), or if married filing separately, ($1,500)",
          "checked": "2026-10-12"
        }
      ]
    },
    "unsourced": {}
  },
  "priorYearFigures": [],
  "local": {
    "onStateReturn": [],
    "separateReturns": [],
    "separateReturnsTax": 0,
    "total": 0
  },
  "taxYear": "2026",
  "methodology": "https://quantcalc.app/docs/state-tax-api/",
  "note": "State income tax only. Federal tax, FICA and local levies are not included. Social Security must be the FEDERALLY-TAXABLE portion, not gross benefits.",
  "perPerson": [
    {
      "role": "primary",
      "age": 67,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "capped_exclusion",
      "retirementExcluded": 63000,
      "retirementRule": "pooled_retirement_and_investment_exclusion",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 0,
      "seniorRule": "none"
    },
    {
      "role": "spouse",
      "age": 63,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "capped_exclusion",
      "retirementExcluded": 31000,
      "retirementRule": "pooled_retirement_and_investment_exclusion",
      "earnedIncomeExcluded": 5000,
      "seniorSubtraction": 0,
      "seniorRule": "none"
    }
  ],
  "breakdown": {
    "taxableIncome": 13000,
    "socialSecurityInBase": 0,
    "retirementInBase": 0,
    "conversionInBase": 0,
    "capitalGainsInBase": 0,
    "militaryExcluded": 0,
    "retirementExcluded": 94000,
    "earnedIncomeExcluded": 5000,
    "seniorSubtraction": 0,
    "militaryCredit": 0,
    "qualifiedDividendsExcluded": 0
  },
  "inputsNotSupplied": [],
  "notModelled": [
    {
      "id": "GA-global-767fb6d9",
      "category": "business",
      "description": "Business income rules: pass-through entity taxes, net operating losses, depreciation differences and other state additions and subtractions outside the income types listed on the API reference.",
      "lines": [
        {
          "form": "SCH1",
          "line": "1",
          "description": "Interest on non-Georgia municipal and state bonds (addition)"
        },
        {
          "form": "SCH1",
          "line": "5",
          "description": "Other additions"
        },
        {
          "form": "SCH1",
          "line": "9",
          "description": "Path2College 529 plan contributions"
        },
        {
          "form": "SCH1",
          "line": "10",
          "description": "Interest on United States obligations"
        },
        {
          "form": "SCH1",
          "line": "12",
          "description": "Other adjustments (booklet list: railroad retirement, other-state refunds, combat pay, HDHP premiums, Georgia bonds, first-responder payments, surviving family member of a veteran, and the rest)"
        },
        {
          "form": "SCH1-P2",
          "line": "13",
          "description": "Rental, royalty, partnership, S corp income"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs business income or adjustment details the request does not carry.",
      "source": {
        "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
        "quote": "Interest on Non-Georgia Municipal and State Bonds"
      }
    },
    {
      "id": "GA-global-cd7f5d31",
      "category": "itemized",
      "description": "Itemized deductions, and credits other than those each state page lists (dependent, earned-income, property-tax, renter, child and similar credits).",
      "lines": [
        {
          "form": "500",
          "line": "12",
          "description": "Itemized deductions (instead of line 11)"
        },
        {
          "form": "500",
          "line": "12a",
          "description": "Itemized deductions (instead of line 11)"
        },
        {
          "form": "500",
          "line": "12b",
          "description": "Itemized deductions (instead of line 11)"
        },
        {
          "form": "500",
          "line": "12c",
          "description": "Itemized deductions (instead of line 11)"
        },
        {
          "form": "500",
          "line": "19",
          "description": "Georgia eligible itemizer tax credit"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs itemized deduction amounts, which the request does not carry.",
      "source": {
        "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
        "quote": "Total Itemized Deductions used in computing Federal Taxable Income."
      }
    },
    {
      "id": "GA-global-fd1da389",
      "category": "dependent-care",
      "description": "Dependents: the dependents input (each dependent's age, and whether a student or disabled) applies every nonrefundable dependent exemption, deduction and credit each state page lists (engine 1.7.0), and counts the qualifying children of the earned income credits (engine 1.12.0). Not calculated: refundable child tax credits and other refundable credits a state page does not list, credits that need expenses (child and dependent care, education) and facts the input does not carry (adoption, custody, certification); each state page lists its own.",
      "lines": [
        {
          "form": "500",
          "line": "20 other IND-CR",
          "description": "Other IND-CR credits: disabled person home purchase/retrofit (201), child and dependent care (202), qualified caregiving expense (204), adoption of a foster child, and the rest"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
        "quote": "Qualified Caregiving Expense Credit - Tax Credit 204"
      }
    },
    {
      "id": "GA-state-5a667692",
      "category": "other",
      "description": "The low income credit on a married-filing-separately return (limited to the joint-return credit, which needs the spouse's income): none is given.",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://web.archive.org/web/20260423205532id_/https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
        "quote": "Taxpayers filing a separate return for a taxable year in which a joint return could have been filed can only claim the credit"
      }
    },
    {
      "id": "GA-state-c8202921",
      "category": "other",
      "description": "Unborn dependents (Form 500 line 7b, a child with a detectable heartbeat): the dependents input lists people claimed on the federal return, so no line 14 amount is given for them.",
      "lines": [
        {
          "form": "500",
          "line": "7b",
          "description": "Number of unborn dependents (detectable heartbeat)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://dor.georgia.gov/document/document/2025-it-511-individual-income-tax-booklet/download",
        "quote": "Number of Unborn Dependents"
      }
    }
  ],
  "stateDocs": "https://quantcalc.app/docs/state-tax/states/ga/",
  "engineVersion": "1.14.2"
}

A public pension, a conversion and an early withdrawal (New York)

The primary (64) has a public pension, an IRA distribution and a Roth conversion in separate fields; the spouse (58) has wages and an IRA withdrawal taken before 59½ with no federal exception (earlyDistributions, earlyDistributionException). perPerson shows what each spouse excluded and breakdown what entered the base.

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "NY",
  "filingStatus": "mfj",
  "age": 64,
  "pensionPublic": 52000,
  "iraDistributions": 18000,
  "rothConversion": 25000,
  "shortTermGains": 3000,
  "socialSecurity": 0,
  "socialSecurityGross": 0,
  "spouse": {
    "age": 58,
    "wages": 65000,
    "iraDistributions": 6000,
    "earlyDistributions": 6000,
    "earlyDistributionException": "none"
  }
}

Returns tax $4,038.70 (effective rate 2.3898%), engine version 1.14.2.

The complete response

{
  "state": "NY",
  "stateName": "New York",
  "tax": 4038.7,
  "effectiveRate": 0.023897633136094675,
  "totalTax": 4038.7,
  "refundableCredits": {
    "total": 0,
    "items": []
  },
  "netTax": 4038.7,
  "input": {
    "filingStatus": "mfj",
    "age": 64,
    "ordinaryIncome": 0,
    "socialSecurity": 0,
    "capitalGains": 0,
    "wages": 0,
    "iraDistributions": 18000,
    "pensionPublic": 52000,
    "rothConversion": 25000,
    "shortTermGains": 3000,
    "socialSecurityGross": 0,
    "spouse": {
      "age": 58,
      "wages": 65000,
      "iraDistributions": 6000,
      "pensionPrivate": 0,
      "pensionPublic": 0,
      "pensionMilitary": 0,
      "rothConversion": 0,
      "earlyDistributions": 6000,
      "earlyDistributionException": "none"
    }
  },
  "rules": {
    "taxesSocialSecurity": false,
    "socialSecurityRule": "exempt",
    "bracketCount": 9,
    "standardDeduction": 16050,
    "personalExemption": 0,
    "seniorSubtraction": 0,
    "seniorSubtractionMinAge": 0,
    "capitalGainsTaxedAsOrdinary": true,
    "capitalGainsInclusionRatio": 1,
    "retirementIncomeExclusion": {
      "cap": 40000,
      "minAge": 59,
      "partialCap": 0,
      "partialMinAge": 0,
      "incomeLimit": 0,
      "reducedBySocialSecurity": false
    },
    "militaryRetirement": {
      "treatment": "exempt",
      "cap": null,
      "minAge": 0,
      "capBelowMinAge": null,
      "percentExempt": null,
      "incomeLimit": null,
      "incomeLimitPhaseoutRange": null,
      "sharesGeneralExclusion": true,
      "earnedIncomeBonus": null,
      "earnedIncomeThreshold": null,
      "reducedBySocialSecurity": false,
      "creditRate": null,
      "perTaxpayer": true
    },
    "wages": {
      "treatment": "ordinary_income",
      "earnedIncomeInRetirementExclusion": null
    },
    "localTax": {
      "included": false,
      "rate": null,
      "basis": "none"
    },
    "sources": {
      "rates": [
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105 Estimated Income Tax Payment Voucher for Individuals (2026)",
          "kind": "instructions",
          "official": true,
          "quote": "IT-2105-I (2026)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.irs.gov/newsroom/irs-releases-tax-inflation-adjustments-for-tax-year-2026-including-amendments-from-the-one-big-beautiful-bill",
          "title": "Irs releases tax inflation adjustments for tax year 2026 including amendments from the one big beautiful bill",
          "kind": "legislation",
          "official": true,
          "quote": "for heads of households, the standard deduction will be $24,150",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "2025 IT-201 instructions",
          "kind": "instructions",
          "official": true,
          "quote": "Married filing separate return",
          "checked": "2026-10-12"
        }
      ],
      "deductions": [
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105 Estimated Income Tax Payment Voucher for Individuals (2026)",
          "kind": "instructions",
          "official": true,
          "quote": "Single and you cannot be claimed as a dependent on another taxpayer",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.irs.gov/newsroom/irs-releases-tax-inflation-adjustments-for-tax-year-2026-including-amendments-from-the-one-big-beautiful-bill",
          "title": "Irs releases tax inflation adjustments for tax year 2026 including amendments from the one big beautiful bill",
          "kind": "legislation",
          "official": true,
          "quote": "for heads of households, the standard deduction will be $24,150",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "New York State Department of Taxation and Finance: it201i_2025.pdf",
          "kind": "instructions",
          "official": true,
          "quote": "Use New York State household credit table 2.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it221i_2025.pdf",
          "title": "New York State Department of Taxation and Finance: it221i_2025.pdf",
          "kind": "instructions",
          "official": true,
          "quote": "Generally, the most you can exclude is $5,200.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it215_2025_fill_in.pdf",
          "title": "Form IT-215 (2025) Claim for Earned Income Credit",
          "kind": "instructions",
          "official": true,
          "quote": "New York State earned income credit (NYS EIC) rate 30% (.30)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it215i_2025.pdf",
          "title": "Instructions for Form IT-215 (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Line 2: If your investment income is more than $11,950, you cannot",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201_2025_fill_in.pdf",
          "title": "Form IT-201 (2025) Resident Income Tax Return",
          "kind": "instructions",
          "official": true,
          "quote": "Payments and refundable credits 63 Empire State child credit",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it214_2025_fill_in.pdf",
          "title": "Form IT-214 (2025) Claim for Real Property Tax Credit",
          "kind": "instructions",
          "official": true,
          "quote": "If line 8 is more than $18,000, stop; you do not qualify for this credit.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it214i_2025.pdf",
          "title": "Instructions for Form IT-214 (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "the credit can be as much as $375.",
          "checked": "2026-10-12"
        }
      ],
      "retirement_income": [
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "Instructions for Form IT-201 Full-Year Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Line 29: Pension and annuity income exclusion",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201_2025_fill_in.pdf",
          "title": "Form IT-201 Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Taxable amount of IRA distributions",
          "checked": "2026-10-12"
        }
      ],
      "public_pension": [
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "Instructions for Form IT-201 Full-Year Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Line 26: Pensions of New York State and local governments and the federal government",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201_2025_fill_in.pdf",
          "title": "Form IT-201 Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Pensions of NYS and local governments and the federal government",
          "checked": "2026-10-12"
        }
      ],
      "roth_conversion": [
        {
          "url": "https://www.tax.ny.gov/pdf/memos/income/m98_7i.pdf",
          "title": "TSB-M-98(7)I: Roth IRAs (Technical Services Bureau Memorandum, December 24, 1998)",
          "kind": "agency_page",
          "official": true,
          "quote": "New York conforms in all respects to the federal income tax treatment of Roth IRAs",
          "checked": "2026-10-12"
        }
      ],
      "capital_gains": [
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201_2025_fill_in.pdf",
          "title": "Form IT-201 Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Capital gain or loss (if required, submit a copy of federal Schedule D",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "2025 Form IT-201 Instructions",
          "kind": "instructions",
          "official": true,
          "quote": "gross income is your federal adjusted gross income after certain",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.irs.gov/pub/irs-pdf/f1040sd.pdf",
          "title": "2025 Schedule D (Form 1040), Capital Gains and Losses",
          "kind": "federal",
          "official": true,
          "quote": "If line 16 is a loss, enter here and on Form 1040, 1040-SR, or 1040-NR, line 7a, the smaller of: • The loss on line 16; or • ($3,000), or if married filing separately, ($1,500)",
          "checked": "2026-10-12"
        }
      ],
      "local_tax": [
        {
          "url": "https://web.archive.org/web/20251107162049/https://www.nysenate.gov/legislation/laws/TAX/1303",
          "title": "NY Tax Law § 1303. City taxable income (Wayback copy of nysenate.gov; live site Cloudflare-blocked)",
          "kind": "statute",
          "official": true,
          "quote": "The city taxable income of a city resident individual shall mean and be the same as his or her New York taxable income",
          "checked": "2026-10-01"
        },
        {
          "url": "https://web.archive.org/web/20251114213033/https://www.nysenate.gov/legislation/laws/TAX/1302",
          "title": "NY Tax Law § 1302. Persons subject to tax (Wayback copy)",
          "kind": "statute",
          "official": true,
          "quote": "imposed for each taxable year on the city taxable income of every city resident individual, estate and trust",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20251209112301/https://www.nysenate.gov/legislation/laws/TAX/1305",
          "title": "NY Tax Law § 1305. City resident and city nonresident defined (Wayback copy)",
          "kind": "statute",
          "official": true,
          "quote": "who is domiciled in the city wherein the tax is imposed",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105, Estimated Income Tax Payment Voucher for Individuals (IT-2105-I, 2026)",
          "kind": "instructions",
          "official": true,
          "quote": "Line 22a – The current rate for Yonkers is 16.75% (.1675). If you are",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/publications/withholding/nys50_t_y.pdf",
          "title": "NYS-50-T-Y (1/26) Yonkers Withholding Tax Tables and Methods, effective January 1, 2026",
          "kind": "agency_page",
          "official": true,
          "quote": "Effective January 1, 2026 – December 31, 2026",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "Instructions for Form IT-201, Full-Year Resident Income Tax Return (IT-201-I, 2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Yonkers worksheet",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it360_1i_2025.pdf",
          "title": "Instructions for Form IT-360.1 Change of City Resident Status (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Enter in Column B that part of the income included in Column A\nthat you received from all sources while you were a New York\nCity resident.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "Instructions for Form IT-201 Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Table 2 - Part-year New York City residents:\nNew York City school tax credit proration chart",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it215i_2025.pdf",
          "title": "Instructions for Form IT-215 Claim for Earned Income Credit (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "9 Part-year NYC resident EIC (multiply line 5 by line 8). Enter this amount on\n\t\t  Form IT-215, line 27; and on Form IT-201, line 70, or on Form IT-203-ATT, line 11.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it360_1_2025_fill_in.pdf",
          "title": "Form IT-360.1 Change of City Resident Status (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "47 New York City taxable income (subtract line 46 from line 45)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it360_1i_2025.pdf",
          "title": "Instructions for Form IT-360.1 Change of City Resident Status (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Enter in the applicable column your income percentage from the\nworksheet below.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/y203i_2025.pdf",
          "title": "Instructions for Form Y-203 Yonkers Nonresident Earnings Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "If you are married, you\ncannot file a joint Yonkers nonresident earnings tax return. If you each\nhave taxable earnings, you each must use a separate Form Y-203 to\ncalculate your tax.",
          "checked": "2026-10-12"
        }
      ],
      "surtax": [
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105 Estimated Income Tax Payment Voucher for Individuals (2026)",
          "kind": "instructions",
          "official": true,
          "quote": "If your NYAGI is more than $107,650",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "It201i 2025",
          "kind": "instructions",
          "official": true,
          "quote": "and your taxable income (line 38) is $269,300 or less, then you must calculate your tax using this worksheet",
          "checked": "2026-10-12"
        }
      ]
    },
    "unsourced": {}
  },
  "priorYearFigures": [],
  "local": {
    "onStateReturn": [],
    "separateReturns": [],
    "separateReturnsTax": 0,
    "total": 0
  },
  "taxYear": "2026",
  "methodology": "https://quantcalc.app/docs/state-tax-api/",
  "note": "State income tax only. Federal tax, FICA and local levies are not included. Social Security must be the FEDERALLY-TAXABLE portion, not gross benefits.",
  "perPerson": [
    {
      "role": "primary",
      "age": 64,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "exempt",
      "retirementExcluded": 72000,
      "retirementRule": "capped_exclusion",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 0,
      "seniorRule": "none"
    },
    {
      "role": "spouse",
      "age": 58,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "exempt",
      "retirementExcluded": 0,
      "retirementRule": "capped_exclusion",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 0,
      "seniorRule": "none"
    }
  ],
  "breakdown": {
    "taxableIncome": 80950,
    "socialSecurityInBase": 0,
    "retirementInBase": 29000,
    "conversionInBase": 0,
    "capitalGainsInBase": 0,
    "militaryExcluded": 0,
    "retirementExcluded": 72000,
    "earnedIncomeExcluded": 0,
    "seniorSubtraction": 0,
    "militaryCredit": 0
  },
  "inputsNotSupplied": [
    {
      "input": "localities",
      "family": "local_tax",
      "assumed": "no local income tax beyond the state's (Indiana and Maryland: the county average)",
      "probed": "the highest-rate jurisdiction of each kind of residence the state has (NYC for New York)",
      "taxMin": 4038.7,
      "taxMax": 6956.7865,
      "totalTaxMin": 4038.7,
      "totalTaxMax": 6956.7865,
      "netTaxMin": 4038.7,
      "netTaxMax": 6659.4685
    }
  ],
  "notModelled": [
    {
      "id": "NY-global-9712d4d1",
      "category": "other-state-credit",
      "description": "Other-state credits: the credits for tax paid to other states (a resident's or part-year resident's credit for income tax paid to another state, country or locality, each state's own formula) are not calculated.",
      "lines": [
        {
          "form": "IT-201",
          "line": "41",
          "description": "Resident credit (tax paid to other jurisdictions)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs income taxed by another state or locality, which the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Did you have income from sources outside New York State and pay income tax to another state, a local government"
      }
    },
    {
      "id": "NY-global-fd1da389",
      "category": "dependent-care",
      "description": "Dependents: the dependents input (each dependent's age, and whether a student or disabled) applies every nonrefundable dependent exemption, deduction and credit each state page lists (engine 1.7.0), and counts the qualifying children of the earned income credits (engine 1.12.0). Not calculated: refundable child tax credits and other refundable credits a state page does not list, credits that need expenses (child and dependent care, education) and facts the input does not carry (adoption, custody, certification); each state page lists its own.",
      "lines": [
        {
          "form": "IT-201",
          "line": "64",
          "description": "NYS / NYC child and dependent care credit"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Line 64: New York State and New York City child and dependent care credits"
      }
    },
    {
      "id": "NY-locality-a5a85a47",
      "category": "dependent-care",
      "description": "The NYC child and dependent care credit (needs expenses).",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it216i_2025.pdf",
        "quote": "as 75% of the New York State child and dependent care credit,"
      }
    },
    {
      "id": "NY-state-43f9c9a6",
      "category": "business",
      "description": "The NYC taxes on lump-sum and accumulation distributions and the NYC unincorporated business tax credit (IT-201 lines 51 and 53) are not calculated.",
      "lines": [
        {
          "form": "IT-201",
          "line": "51-53",
          "description": "Other NYC taxes (lump-sum and accumulation distributions) and NYC nonrefundable credits (UBT credit)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs business income or adjustment details the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Can you claim the New York City unincorporated business"
      }
    },
    {
      "id": "NY-state-7b1c5618",
      "category": "other",
      "description": "The Empire State child credit is refundable and is not calculated.",
      "lines": [
        {
          "form": "IT-201",
          "line": "63",
          "description": "Empire State child credit (refundable)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "If you qualify, complete Form IT-213, and transfer the amount from Form IT-213 to Form IT-201, line 63."
      }
    },
    {
      "id": "NY-state-af0829b6",
      "category": "other",
      "description": "The NYC income tax elimination credit (IT-201 line 70a, for NYC residents at low income) is not calculated; the NYC earned income credit and the NYC school tax credits are (refundableCredits, with an NY-NYC locality, engine 1.12.0). The real property tax credit (IT-214) reads rentPaid as adjusted rent (rent less any rent subsidy) and, with rentIncludesHeat, applies the form's adjustment for rent that includes heat; rent that also includes gas, electricity or furnishings, which the form adjusts further, is not an input.",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Line 70a: New York City income tax elimination credit"
      }
    },
    {
      "id": "NY-state-e41aa725",
      "category": "locality",
      "description": "A part-year New York City resident's NYC earned income credit (IT-215 Worksheet C, the period's income percentage) is not calculated: refundableCredits and netTax leave it out on a part-year NYC return. The NYC school tax credits are (engine 1.13.1: the fixed amount from the Table 2 proration chart, the rate-reduction amount on IT-360.1 line 47; IT-201 lines 69 and 69a, or IT-203 lines 60 and 60a for a part-year state resident).",
      "lines": [
        {
          "form": "IT-201",
          "line": "70 (part-year NYC)",
          "description": "A part-year NYC resident's NYC earned income credit (IT-215 Worksheet C line 9, line 70); the part-year NYC school tax credits (lines 69 and 69a, Table 2 and IT-360.1 line 47) are calculated (engine 1.13.1)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It depends on where the household lives or works: the engine covers the jurisdictions of its locality registry only.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Table 2 - Part-year New York City residents: New York City school tax credit proration chart"
      }
    },
    {
      "id": "NY-state-ed2572ea",
      "category": "other",
      "description": "The pension and annuity exclusion of a beneficiary under 59 (allowed when the person who died would have been 59 and a half) is not calculated: the engine reads a decedent's age only for South Carolina's surviving-spouse deduction (deceasedSpouseAge), so a survivor under 59 gets none here.",
      "lines": [
        {
          "form": "IT-201",
          "line": "29 beneficiary",
          "description": "Line 29 for a beneficiary: allowed when the decedent would have been 59½, whatever the beneficiary's age"
        },
        {
          "form": "statute",
          "line": "IT-201-I line 29 Beneficiaries",
          "description": "Pension exclusion of a beneficiary follows the decedent's age"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "if the decedent would have been entitled to it, had the decedent continued to live, regardless of your age"
      }
    },
    {
      "id": "NY-state-fc6a47aa",
      "category": "other",
      "description": "The disability income exclusion's combined limit with the pension exclusion is not applied (it binds only when a person under 65 has disability pay and more other excluded pension income than the exclusion leaves), and on a married-filing-separately return none is given (it needs the spouses to have lived apart).",
      "lines": [
        {
          "form": "IT-221",
          "line": "MFS / combined limit",
          "description": "IT-221 on a separate return (spouses lived apart all year) and the combined limit with the pension exclusion"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it221i_2025.pdf",
        "quote": "The total of your disability income exclusion and any pension and annuity income exclusion you claim cannot exceed $20,000."
      }
    }
  ],
  "stateDocs": "https://quantcalc.app/docs/state-tax/states/ny/",
  "engineVersion": "1.14.2"
}

A military retiree with dependents (Colorado)

Military retirement pay has its own field. The retiree is 52, below the age of Colorado's full subtraction, so the capped amount for younger retirees applies: rules.militaryRetirement shows the age and the cap, perPerson[0].militaryExcluded the amount.

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "CO",
  "filingStatus": "mfj",
  "age": 52,
  "pensionMilitary": 38000,
  "wages": 61000,
  "spouse": {
    "age": 50,
    "wages": 42000
  },
  "dependents": [
    {
      "age": 14
    },
    {
      "age": 17
    }
  ]
}

Returns tax $4,127.20 (effective rate 2.9271%), engine version 1.14.2.

The complete response

{
  "state": "CO",
  "stateName": "Colorado",
  "tax": 4127.2,
  "effectiveRate": 0.0292709219858156,
  "totalTax": 4127.2,
  "refundableCredits": {
    "total": 0,
    "items": []
  },
  "netTax": 4127.2,
  "input": {
    "filingStatus": "mfj",
    "age": 52,
    "ordinaryIncome": 0,
    "socialSecurity": 0,
    "capitalGains": 0,
    "wages": 61000,
    "pensionMilitary": 38000,
    "dependents": [
      {
        "age": 14,
        "student": false,
        "disabled": false
      },
      {
        "age": 17,
        "student": false,
        "disabled": false
      }
    ],
    "spouse": {
      "age": 50,
      "wages": 42000,
      "iraDistributions": 0,
      "pensionPrivate": 0,
      "pensionPublic": 0,
      "pensionMilitary": 0,
      "rothConversion": 0
    }
  },
  "rules": {
    "taxesSocialSecurity": true,
    "socialSecurityRule": "age_banded_subtraction",
    "bracketCount": 1,
    "standardDeduction": 32200,
    "personalExemption": 0,
    "seniorSubtraction": 0,
    "seniorSubtractionMinAge": 0,
    "capitalGainsTaxedAsOrdinary": true,
    "capitalGainsInclusionRatio": 1,
    "retirementIncomeExclusion": {
      "cap": 0,
      "minAge": 0,
      "partialCap": 0,
      "partialMinAge": 0,
      "incomeLimit": 0,
      "reducedBySocialSecurity": false
    },
    "militaryRetirement": {
      "treatment": "capped_exclusion",
      "cap": 0,
      "minAge": 55,
      "capBelowMinAge": 15000,
      "percentExempt": null,
      "incomeLimit": null,
      "incomeLimitPhaseoutRange": null,
      "sharesGeneralExclusion": true,
      "earnedIncomeBonus": null,
      "earnedIncomeThreshold": null,
      "reducedBySocialSecurity": false,
      "creditRate": null,
      "perTaxpayer": true
    },
    "wages": {
      "treatment": "ordinary_income",
      "earnedIncomeInRetirementExclusion": null
    },
    "localTax": {
      "included": false,
      "rate": null,
      "basis": "none"
    },
    "sources": {
      "rates": [
        {
          "url": "https://tax.colorado.gov/sites/tax/files/documents/DR_1098_Colorado_Withholding_Worksheet_for_Employees.pdf",
          "title": "DR 1098 2026 Colorado Withholding Worksheet for Employers",
          "kind": "instructions",
          "official": true,
          "quote": "Colorado wage withholding for 2026",
          "checked": "2026-10-12"
        },
        {
          "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
          "title": "Book 104 2025 Colorado Individual Income Tax Filing Guide",
          "kind": "instructions",
          "official": true,
          "quote": "The income tax rate is currently 4.4%",
          "checked": "2026-10-12"
        }
      ],
      "deductions": [
        {
          "url": "https://www.irs.gov/newsroom/irs-releases-tax-inflation-adjustments-for-tax-year-2026-including-amendments-from-the-one-big-beautiful-bill",
          "title": "IRS releases tax inflation adjustments for tax year 2026, including amendments from the One, Big, Beautiful Bill",
          "kind": "federal",
          "official": true,
          "quote": "$16,100",
          "checked": "2026-10-12"
        },
        {
          "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
          "title": "Book 104 2025 Colorado Individual Income Tax Filing Guide",
          "kind": "instructions",
          "official": true,
          "quote": "Enter your federal taxable income from your federal income tax form 1040",
          "checked": "2026-10-12"
        },
        {
          "url": "https://tax.colorado.gov/individual-income-tax-guide",
          "title": "Individual Income Tax Guide",
          "kind": "agency_page",
          "official": true,
          "quote": "whose adjusted gross income exceeds $300,000 and who claims either itemized deductions or the standard deduction on their federal return",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.irs.gov/newsroom/irs-releases-tax-inflation-adjustments-for-tax-year-2026-including-amendments-from-the-one-big-beautiful-bill",
          "title": "IRS releases tax inflation adjustments for tax year 2026",
          "kind": "federal",
          "official": true,
          "quote": "for heads of households, the standard deduction will be $24,150",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.law.cornell.edu/uscode/text/26/151",
          "title": "26 U.S.C. § 151",
          "kind": "federal",
          "official": true,
          "quote": "exceeds $75,000 ($150,000 in the case of a joint return)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://tax.colorado.gov/CTC-EITC",
          "title": "Child Tax Credit & Earned Income Tax Credit (web page)",
          "kind": "agency_page",
          "official": true,
          "quote": "The credit was 50% of the federal EITC amount for Tax Years 2024 and 2025, but will be reduced to 25% in Tax Year 2026.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://tax.colorado.gov/sites/tax/files/documents/DR0104TN_2025.pdf",
          "title": "2025 DR 0104TN Colorado EITC for ITIN Filers or Certain Filers Under Age 25",
          "kind": "instructions",
          "official": true,
          "quote": "Age 19-24 at the end of the tax year and not a specified student, or",
          "checked": "2026-10-12"
        }
      ],
      "senior": [
        {
          "url": "https://www.irs.gov/pub/irs-drop/rp-25-32.pdf",
          "title": "Rev. Proc. 2025-32 (2026 inflation adjustments)",
          "kind": "federal",
          "official": true,
          "quote": "the additional standard deduction amount under § 63(f) for the aged or the blind is $1,650. The additional standard deduction amount is increased to $2,050 if the individual is also unmarried and not a surviving spouse.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.irs.gov/pub/irs-pdf/f1040s1a.pdf",
          "title": "Schedule 1-A (Form 1040), Additional Deductions",
          "kind": "federal",
          "official": true,
          "quote": "Enter $75,000 ($150,000 if married filing jointly)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
          "title": "2025 Colorado Individual Income Tax Filing Guide",
          "kind": "instructions",
          "official": true,
          "quote": "Enter your federal taxable income from your federal income tax form 1040, 1040 SR, or 1040 SP, line 15.",
          "checked": "2026-10-12"
        }
      ],
      "retirement_income": [
        {
          "url": "https://tax.colorado.gov/sites/tax/files/documents/ITT_Social_Security_Pensions_and_Annuities_Jan_2025.pdf",
          "title": "Income Tax Topics: Social Security, Pensions, and Annuities (Revised January 2025)",
          "kind": "agency_page",
          "official": true,
          "quote": "$20,000 each year or, for individuals age 65 or older, $24,000",
          "checked": "2026-10-12"
        },
        {
          "url": "https://tax.colorado.gov/retirees",
          "title": "Individual Income Tax | Information for Retirees",
          "kind": "agency_page",
          "official": true,
          "quote": "can subtract the smaller of $20,000 or the taxable pension/annuity income",
          "checked": "2026-10-12"
        },
        {
          "url": "https://tax.colorado.gov/retired-servicemembers",
          "title": "Retired Servicemembers",
          "kind": "guidance",
          "official": false,
          "quote": "A retired servicemember may claim one of two subtractions for all or part of the military retirement benefits that are included in their federal taxable income.",
          "checked": "2026-10-12"
        }
      ],
      "military_retirement": [
        {
          "url": "https://tax.colorado.gov/retired-servicemembers",
          "title": "Retired servicemembers",
          "kind": "agency_page",
          "official": true,
          "quote": "If a retired servicemember is under 55 years of age at the end of the tax year",
          "checked": "2026-10-12"
        },
        {
          "url": "https://leg.colorado.gov/bills/HB26-1062",
          "title": "HB26 1062",
          "kind": "legislation",
          "official": true,
          "quote": "Postpone Indefinitely",
          "checked": "2026-10-12"
        }
      ],
      "federal_interaction": [
        {
          "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
          "title": "Book 104 2025 Colorado Individual Income Tax Filing Guide",
          "kind": "instructions",
          "official": true,
          "quote": "Enter your federal taxable income from your federal income tax form 1040",
          "checked": "2026-10-12"
        }
      ]
    },
    "unsourced": {}
  },
  "priorYearFigures": [],
  "local": {
    "onStateReturn": [],
    "separateReturns": [],
    "separateReturnsTax": 0,
    "total": 0
  },
  "taxYear": "2026",
  "methodology": "https://quantcalc.app/docs/state-tax-api/",
  "note": "State income tax only. Federal tax, FICA and local levies are not included. Social Security must be the FEDERALLY-TAXABLE portion, not gross benefits.",
  "perPerson": [
    {
      "role": "primary",
      "age": 52,
      "militaryPay": 38000,
      "militaryExcluded": 15000,
      "militaryRule": "capped_exclusion",
      "retirementExcluded": 0,
      "retirementRule": "co_pension_and_ss_subtraction",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 0,
      "seniorRule": "senior_subtraction"
    },
    {
      "role": "spouse",
      "age": 50,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "capped_exclusion",
      "retirementExcluded": 0,
      "retirementRule": "co_pension_and_ss_subtraction",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 0,
      "seniorRule": "senior_subtraction"
    }
  ],
  "breakdown": {
    "taxableIncome": 93800,
    "socialSecurityInBase": 0,
    "retirementInBase": 23000,
    "conversionInBase": 0,
    "capitalGainsInBase": 0,
    "militaryExcluded": 15000,
    "retirementExcluded": 0,
    "earnedIncomeExcluded": 0,
    "seniorSubtraction": 0,
    "militaryCredit": 0
  },
  "inputsNotSupplied": [
    {
      "input": "blind",
      "family": "blind_disability",
      "assumed": "not blind",
      "probed": "true",
      "taxMin": 4054.6,
      "taxMax": 4127.2,
      "totalTaxMin": 4054.6,
      "totalTaxMax": 4127.2,
      "netTaxMin": 4054.6,
      "netTaxMax": 4127.2
    },
    {
      "input": "spouse.blind",
      "family": "blind_disability",
      "assumed": "not blind",
      "probed": "true",
      "taxMin": 4054.6,
      "taxMax": 4127.2,
      "totalTaxMin": 4054.6,
      "totalTaxMax": 4127.2,
      "netTaxMin": 4054.6,
      "netTaxMax": 4127.2
    },
    {
      "input": "survivorBenefits",
      "family": "retirement_income",
      "assumed": "the retirement income is the person's own, not a survivor's",
      "probed": "true",
      "taxMin": 3907.2,
      "taxMax": 4127.2,
      "totalTaxMin": 3907.2,
      "totalTaxMax": 4127.2,
      "netTaxMin": 3907.2,
      "netTaxMax": 4127.2
    }
  ],
  "notModelled": [
    {
      "id": "CO-global-584cdfa6",
      "category": "amt",
      "description": "State alternative minimum taxes.",
      "lines": [
        {
          "form": "DR 0104",
          "line": "14",
          "description": "Alternative minimum tax (DR 0104AMT)"
        },
        {
          "form": "DR 0104AMT",
          "line": "all",
          "description": "Colorado alternative minimum tax"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on preference items and income the request does not carry.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "Generally, if you owe alternative minimum tax on your federal income tax return, you will also owe it for your Colorado return"
      }
    },
    {
      "id": "CO-global-7c8fdb0e",
      "category": "tax-table",
      "description": "Tax-table lookups: where a state's instructions have filers look tax up in a table of income bands, the engine applies the rate schedule to the exact amount.",
      "lines": [
        {
          "form": "DR 0104",
          "line": "13 (table)",
          "description": "Tax-table lookup"
        }
      ],
      "couldApply": true,
      "reason": "The form looks the tax up in a table of income bands; the engine applies the rate schedule to the exact amount, a difference of a few dollars at most.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "Full-year residents should refer to the tax table in this booklet. Determine the tax for the amount on line 12."
      }
    },
    {
      "id": "CO-global-9712d4d1",
      "category": "other-state-credit",
      "description": "Other-state credits: the credits for tax paid to other states (a resident's or part-year resident's credit for income tax paid to another state, country or locality, each state's own formula) are not calculated.",
      "lines": [
        {
          "form": "DR 0104CR",
          "line": "27-34",
          "description": "Credit for tax paid to another state"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs income taxed by another state or locality, which the request does not carry.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "Colorado resident individuals may claim a credit for income tax accrued to another state for the same tax year"
      }
    },
    {
      "id": "CO-global-cd7f5d31",
      "category": "itemized",
      "description": "Itemized deductions, and credits other than those each state page lists (dependent, earned-income, property-tax, renter, child and similar credits).",
      "lines": [
        {
          "form": "DR 0104",
          "line": "1 (itemized)",
          "description": "Federal taxable income of a filer who itemizes"
        },
        {
          "form": "DR 0104",
          "line": "2",
          "description": "State income tax addback (itemizers)"
        },
        {
          "form": "DR 0104",
          "line": "17",
          "description": "Nonrefundable credits from DR 0104CR line 65"
        },
        {
          "form": "DR 0104CR",
          "line": "37-64",
          "description": "Other nonrefundable credits (historic property, child care center / employer child care / contribution credits, school-to-career, Colorado Works, long-term care insurance, job growth, housing, rural zone, preceptor, visitability, organ donation leave, wildfire mitigation, enterprise zone contribution, energy storage, homeless contribution, home purchase assistance)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs itemized deduction amounts, which the request does not carry.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "Complete the DR 0104CR to claim various nonrefundable credits. Transfer the amount from the DR 0104CR line 65 to this line."
      }
    },
    {
      "id": "CO-global-fd1da389",
      "category": "dependent-care",
      "description": "Dependents: the dependents input (each dependent's age, and whether a student or disabled) applies every nonrefundable dependent exemption, deduction and credit each state page lists (engine 1.7.0), and counts the qualifying children of the earned income credits (engine 1.12.0). Not calculated: refundable child tax credits and other refundable credits a state page does not list, credits that need expenses (child and dependent care, education) and facts the input does not carry (adoption, custody, certification); each state page lists its own.",
      "lines": [
        {
          "form": "DR 0104CR",
          "line": "7-8, 10-23, 25",
          "description": "Other refundable credits (business personal property, renewable energy, early childhood educator, composite / SALT parity tax, employee-owned business, transportation, heat pump, energy storage, greenhouse gas, food accessibility, lawn equipment, CHIPS zone, Colorado Promise, aircraft, apprenticeship, qualified care worker)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "Line 10 Early Childhood Educator Income Tax Credit If you were an early childhood educator for at least six months during tax year 2025"
      }
    },
    {
      "id": "CO-locality-fcbee0a3",
      "category": "locality",
      "description": "Per-worker head taxes and employer payroll taxes: Alabama occupational taxes (Birmingham), Colorado occupational privilege taxes (Denver, Aurora, Greenwood Village, Glendale, Sheridan), the Newark payroll tax, West Virginia city service fees, the Portland Arts Tax, the TriMet and Lane transit self-employment taxes, the Pennsylvania Local Services Tax: flat or employer levies, not taxes on the household's income.",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It depends on where the household lives or works: the engine covers the jurisdictions of its locality registry only.",
      "source": {
        "url": "https://www.birminghamal.gov/government/city-departments/finance/tax-license-division",
        "quote": "Lodging Tax Occupational Tax Sales Tax"
      }
    },
    {
      "id": "CO-provenance-95eb1a0c",
      "category": "other",
      "description": "The PERA/DPSRS contribution-basis subtraction is not modeled.",
      "lines": [
        {
          "form": "DR 0104AD",
          "line": "14",
          "description": "PERA / DPSRS subtraction (1984-1986 contributions)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "Line 14 PERA/DPSRS Subtraction If you made contributions to PERA between July 1, 1984, and December 31, 1986"
      }
    },
    {
      "id": "CO-state-356f6717",
      "category": "business",
      "description": "Additions for other states' bond interest and for nonqualified CollegeInvest or Colorado ABLE distributions are not calculated: that income is not among the inputs.",
      "lines": [
        {
          "form": "DR 0104",
          "line": "6",
          "description": "Nonqualified CollegeInvest distributions"
        },
        {
          "form": "DR 0104",
          "line": "7",
          "description": "Nonqualified Colorado ABLE distributions"
        },
        {
          "form": "DR 0104",
          "line": "9",
          "description": "Other additions: non-Colorado state and local bond interest, conservation easement, alien labor, fiduciary adjustments, restricted clubs, forfeited home-savings subtractions"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs business income or adjustment details the request does not carry.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "Line 6 Non-qualifying Distribution addback (CollegeInvest Tuition Savings) An account holder must make an addition on their Colorado return"
      }
    },
    {
      "id": "CO-state-53fc0b92",
      "category": "dependent-care",
      "description": "The child tax credit, the Family Affordability credit and the child care credit are refundable (or need expenses) and are not calculated.",
      "lines": [
        {
          "form": "DR 0104CR",
          "line": "1",
          "description": "Child tax credit (refundable)"
        },
        {
          "form": "DR 0104CR",
          "line": "2",
          "description": "Child and dependent care expenses credit (refundable, DR 0347)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "If you check the Child Tax Credit box, go to form DR 0104CN to determine whether you qualify for the Colorado child tax credit"
      }
    },
    {
      "id": "CO-state-62eaa69d",
      "category": "itemized",
      "description": "Subtractions for state income tax refunds, interest on United States government obligations, family and medical leave insurance benefits, charitable contributions of filers who do not itemize, CollegeInvest and Colorado ABLE contributions, qualified reservation income and active-duty pay after reacquiring Colorado residency are not calculated: the inputs do not separate these amounts.",
      "lines": [
        {
          "form": "DR 0104AD",
          "line": "1",
          "description": "State income tax refund"
        },
        {
          "form": "DR 0104AD",
          "line": "2",
          "description": "U.S. government interest"
        },
        {
          "form": "DR 0104AD",
          "line": "10",
          "description": "CollegeInvest contribution"
        },
        {
          "form": "DR 0104AD",
          "line": "11",
          "description": "Colorado ABLE contribution"
        },
        {
          "form": "DR 0104AD",
          "line": "12",
          "description": "Qualifying charitable contributions of non-itemizers (over $500)"
        },
        {
          "form": "DR 0104AD",
          "line": "13",
          "description": "Qualified reservation income"
        },
        {
          "form": "DR 0104AD",
          "line": "17",
          "description": "Reacquisition of Colorado residency during active duty (active-duty pay)"
        },
        {
          "form": "DR 0104AD",
          "line": "19",
          "description": "FAMLI benefits received"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs itemized deduction amounts, which the request does not carry.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "Line 13 Qualified Reservation Income List any amount of income that was derived wholly from reservation sources by an enrolled tribal member"
      }
    },
    {
      "id": "CO-state-a2d28619",
      "category": "other",
      "description": "The Social Security subtraction for benefits received under age 55 because of the death of the person entitled to them is calculated only when socialSecuritySurvivor says so (engine 1.8.0): without it such benefits are taxed.",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "you can claim the subtraction only for social security benefits you received due to the death of the person originally entitled to the benefits"
      }
    },
    {
      "id": "CO-state-ac975988",
      "category": "other",
      "description": "The disability assistance credit (a refundable credit for a filer with a full year of disability benefits and low income) is not calculated: it depends on the source of the benefits and an income test the inputs do not carry.",
      "lines": [
        {
          "form": "DR 0104CR",
          "line": "24",
          "description": "Disability assistance credit (refundable)"
        },
        {
          "form": "Book 104 (2025), DR 0104AD line 3",
          "line": "Disability",
          "description": "Social Security disability benefits under 55"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf",
        "quote": "Line 24 Disability Assistance Credit You may claim this credit only if you meet several requirements."
      }
    }
  ],
  "stateDocs": "https://quantcalc.app/docs/state-tax/states/co/",
  "engineVersion": "1.14.2"
}

A railroad retiree (Vermont)

Every benefit is Railroad Retirement Tier 1, so railroadRetirementTier1 equals socialSecurityGross; its taxable share and the Tier 2 annuity are kept out of the Vermont base (breakdown.railroadExcluded), while the IRA distribution is taxed.

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "VT",
  "filingStatus": "single",
  "age": 68,
  "socialSecurity": 19550,
  "socialSecurityGross": 31000,
  "railroadRetirementTier1": 31000,
  "railroadRetirementTier2": 16800,
  "iraDistributions": 32000,
  "ordinaryIncome": 1200
}

Returns tax $626.45 (effective rate 0.9007%), engine version 1.14.2.

The complete response

{
  "state": "VT",
  "stateName": "Vermont",
  "tax": 626.45,
  "effectiveRate": 0.009007189072609634,
  "totalTax": 626.45,
  "refundableCredits": {
    "total": 0,
    "items": []
  },
  "netTax": 626.45,
  "input": {
    "filingStatus": "single",
    "age": 68,
    "ordinaryIncome": 1200,
    "socialSecurity": 19550,
    "capitalGains": 0,
    "iraDistributions": 32000,
    "socialSecurityGross": 31000,
    "railroadRetirementTier2": 16800,
    "railroadRetirementTier1": 31000
  },
  "rules": {
    "taxesSocialSecurity": true,
    "socialSecurityRule": "ratable_phaseout",
    "bracketCount": 4,
    "standardDeduction": 7850,
    "personalExemption": 5400,
    "seniorSubtraction": 1250,
    "seniorSubtractionMinAge": 65,
    "capitalGainsTaxedAsOrdinary": true,
    "capitalGainsInclusionRatio": 1,
    "retirementIncomeExclusion": {
      "cap": 0,
      "minAge": 0,
      "partialCap": 0,
      "partialMinAge": 0,
      "incomeLimit": 0,
      "reducedBySocialSecurity": false
    },
    "militaryRetirement": {
      "treatment": "exempt",
      "cap": null,
      "minAge": 0,
      "capBelowMinAge": null,
      "percentExempt": null,
      "incomeLimit": 125000,
      "incomeLimitPhaseoutRange": 50000,
      "sharesGeneralExclusion": true,
      "earnedIncomeBonus": null,
      "earnedIncomeThreshold": null,
      "reducedBySocialSecurity": false,
      "creditRate": null,
      "perTaxpayer": true
    },
    "wages": {
      "treatment": "ordinary_income",
      "earnedIncomeInRetirementExclusion": null
    },
    "localTax": {
      "included": false,
      "rate": null,
      "basis": "none"
    },
    "sources": {
      "rates": [
        {
          "url": "https://web.archive.org/web/20260312230301id_/https://tax.vermont.gov/sites/tax/files/documents/GB-1210-2026.pdf",
          "title": "GB-1210-2026: 2026 Income Tax Withholding Instructions, Tables, and Charts",
          "kind": "instructions",
          "official": true,
          "quote": "+ 3.35%",
          "checked": "2026-09-27"
        },
        {
          "url": "https://web.archive.org/web/20260203213311id_/https://tax.vermont.gov/sites/tax/files/documents/IN-111-Instr-2025.pdf",
          "title": "2025 Form IN-111 Instructions (Vermont Income Tax Return)",
          "kind": "instructions",
          "official": true,
          "quote": "2025 Vermont Tax Rate Schedules",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20260203205706id_/https://tax.vermont.gov/sites/tax/files/documents/IN-114-Instr-2026.pdf",
          "title": "2026 Form IN-114 Instructions (Vermont estimated income tax), 2026 Preliminary Vermont Tax Rates",
          "kind": "instructions",
          "official": true,
          "quote": "2026 Preliminary Vermont Tax Rates",
          "checked": "2026-09-27"
        }
      ],
      "deductions": [
        {
          "url": "https://web.archive.org/web/20260625100235id_/https://legislature.vermont.gov/statutes/section/32/151/05811",
          "title": "32 V.S.A. § 5811. Definitions",
          "kind": "statute",
          "official": true,
          "quote": "a personal exemption of $4,150.00 per person",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20260312230301id_/https://tax.vermont.gov/sites/tax/files/documents/GB-1210-2026.pdf",
          "title": "GB-1210-2026: 2026 Income Tax Withholding Instructions, Tables, and Charts",
          "kind": "instructions",
          "official": true,
          "quote": "one withholding allowance equals $5400.00",
          "checked": "2026-09-27"
        },
        {
          "url": "https://web.archive.org/web/20260203213311id_/https://tax.vermont.gov/sites/tax/files/documents/IN-111-Instr-2025.pdf",
          "title": "2025 Form IN-111 Instructions (Vermont Income Tax Return)",
          "kind": "instructions",
          "official": true,
          "quote": "Standard 7,650 15,300 7,650 11,450",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20260203201231id_/https://tax.vermont.gov/sites/tax/files/documents/IN-112-Instr-2025.pdf",
          "title": "2025 Schedule IN-112 Instructions",
          "kind": "instructions",
          "official": true,
          "quote": "Vermont Earned Income Tax Credit. If Line 5 is GREATER than zero, MULTIPLY Line 6 by 38% (0.38). If Line",
          "checked": "2026-10-12"
        }
      ],
      "senior": [
        {
          "url": "https://web.archive.org/web/20260124021609id_/https://legislature.vermont.gov/statutes/section/32/151/05822",
          "title": "05822",
          "kind": "statute",
          "official": true,
          "quote": "If the federal adjusted gross income of the taxpayer exceeds $150,000.00, then the tax calculated under this subsection shall be the greater of",
          "checked": "2026-09-27"
        },
        {
          "url": "https://web.archive.org/web/20260203213311id_/https://tax.vermont.gov/sites/tax/files/documents/IN-111-Instr-2025.pdf",
          "title": "IN 111 Instr 2025",
          "kind": "instructions",
          "official": true,
          "quote": "receive an additional deduction of $1,250 for each standard deduction box checked on the federal Form 1040.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20260927104858id_/https://legislature.vermont.gov/statutes/section/32/151/05830e",
          "title": "05830e",
          "kind": "statute",
          "official": true,
          "quote": "the contributory system from which the income is received was based on earnings that were not covered by the Social Security Act",
          "checked": "2026-10-12"
        }
      ],
      "social_security": [
        {
          "url": "https://web.archive.org/web/20260927104858id_/https://legislature.vermont.gov/statutes/section/32/151/05830e",
          "title": "32 V.S.A. § 5830e. Retirement income; Social Security income",
          "kind": "statute",
          "official": true,
          "quote": "is less than or equal to $55,000.00, all federally taxable benefits",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20260203201231id_/https://tax.vermont.gov/sites/tax/files/documents/IN-112-Instr-2025.pdf",
          "title": "2025 Schedule IN-112 Instructions (Vermont Tax Adjustments and Credits)",
          "kind": "instructions",
          "official": true,
          "quote": "is your AGI less than $55,000?",
          "checked": "2026-10-12"
        }
      ],
      "retirement_income": [
        {
          "url": "https://web.archive.org/web/20260625100235id_/https://legislature.vermont.gov/statutes/section/32/151/05811",
          "title": "32 V.S.A. § 5811. Definitions",
          "kind": "statute",
          "official": true,
          "quote": "“Taxable income” means, in the case of an individual, federal adjusted gross income",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20260927104858id_/https://legislature.vermont.gov/statutes/section/32/151/05830e",
          "title": "32 V.S.A. § 5830e. Retirement income; Social Security income",
          "kind": "statute",
          "official": true,
          "quote": "the first $10,000.00 of income received from the Civil Service Retirement System shall be excluded",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20260203213311id_/https://tax.vermont.gov/sites/tax/files/documents/IN-111-Instr-2025.pdf",
          "title": "2025 Form IN-111 instructions (Internet Archive capture)",
          "kind": "instructions",
          "official": true,
          "quote": "Qualified Retirement Plan distributions including IRA, HSA & MSA",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20260203194520id_/https://tax.vermont.gov/sites/tax/files/documents/IN-119-2025.pdf",
          "title": "2025 Schedule IN-119 (Internet Archive capture)",
          "kind": "form",
          "official": false,
          "quote": "Tax from federal Form 4972, Tax on Lump-Sum Distributions",
          "checked": "2026-09-28"
        }
      ],
      "surtax": [
        {
          "url": "https://web.archive.org/web/20260124021609id_/https://legislature.vermont.gov/statutes/section/32/151/05822",
          "title": "05822",
          "kind": "statute",
          "official": true,
          "quote": "If the federal adjusted gross income of the taxpayer exceeds $150,000.00, then the tax calculated under this subsection shall be the greater of",
          "checked": "2026-09-27"
        },
        {
          "url": "https://web.archive.org/web/20260203213311id_/https://tax.vermont.gov/sites/tax/files/documents/IN-111-Instr-2025.pdf",
          "title": "IN 111 Instr 2025",
          "kind": "instructions",
          "official": true,
          "quote": "receive an additional deduction of $1,250 for each standard deduction box checked on the federal Form 1040.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20260927104858id_/https://legislature.vermont.gov/statutes/section/32/151/05830e",
          "title": "05830e",
          "kind": "statute",
          "official": true,
          "quote": "the contributory system from which the income is received was based on earnings that were not covered by the Social Security Act",
          "checked": "2026-10-12"
        }
      ]
    },
    "unsourced": {}
  },
  "priorYearFigures": [
    {
      "parameter": "senior_subtraction_single",
      "rule": "vt-additional-deduction-65-blind",
      "valueYear": 2025,
      "value": 1250,
      "why": "the state has not published the 2026 figure; the latest published one is used"
    }
  ],
  "local": {
    "onStateReturn": [],
    "separateReturns": [],
    "separateReturnsTax": 0,
    "total": 0
  },
  "taxYear": "2026",
  "methodology": "https://quantcalc.app/docs/state-tax-api/",
  "note": "State income tax only. Federal tax, FICA and local levies are not included. Social Security must be the FEDERALLY-TAXABLE portion, not gross benefits.",
  "perPerson": [
    {
      "role": "primary",
      "age": 68,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "exempt",
      "retirementExcluded": 0,
      "retirementRule": "none",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 1250,
      "seniorRule": "senior_subtraction"
    }
  ],
  "breakdown": {
    "taxableIncome": 18700,
    "socialSecurityInBase": 0,
    "retirementInBase": 32000,
    "conversionInBase": 0,
    "capitalGainsInBase": 0,
    "militaryExcluded": 0,
    "retirementExcluded": 0,
    "earnedIncomeExcluded": 0,
    "seniorSubtraction": 1250,
    "militaryCredit": 0,
    "railroadExcluded": 36350
  },
  "inputsNotSupplied": [
    {
      "input": "blind",
      "family": "blind_disability",
      "assumed": "not blind",
      "probed": "true",
      "taxMin": 584.575,
      "taxMax": 626.45,
      "totalTaxMin": 584.575,
      "totalTaxMax": 626.45,
      "netTaxMin": 584.575,
      "netTaxMax": 626.45
    }
  ],
  "notModelled": [
    {
      "id": "VT-global-9712d4d1",
      "category": "other-state-credit",
      "description": "Other-state credits: the credits for tax paid to other states (a resident's or part-year resident's credit for income tax paid to another state, country or locality, each state's own formula) are not calculated.",
      "lines": [
        {
          "form": "IN-111",
          "line": "17",
          "description": "Credit for tax paid to other states / provinces (IN-117)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs income taxed by another state or locality, which the request does not carry.",
      "source": {
        "url": "https://web.archive.org/web/20260203213311id_/https://tax.vermont.gov/sites/tax/files/documents/IN-111-Instr-2025.pdf",
        "quote": "Credit for Income Tax Paid To Other State or Canadian Province"
      }
    },
    {
      "id": "VT-state-2c246d06",
      "category": "other",
      "description": "The Vermont credit for the elderly or the disabled (a share of the federal Schedule R credit, IN-119) is not calculated: it depends on the federal credit, which is limited by federal tax.",
      "lines": [
        {
          "form": "IN-111",
          "line": "9 subtractions",
          "description": "IN-119 Part I subtractions: credit for the elderly or the disabled (24% of federal Schedule R), investment tax credit, farm income averaging"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://web.archive.org/web/20260203213311id_/https://tax.vermont.gov/sites/tax/files/documents/IN-111-Instr-2025.pdf",
        "quote": "Credit for the Elderly or the Disabled"
      }
    },
    {
      "id": "VT-state-7c55fff2",
      "category": "part-year",
      "description": "Married couples whose residency differs (engine 1.13.0): when one spouse is a full-year resident and the other a nonresident: Vermont's 2025 instructions word the exception as 'only one spouse has sufficient nexus' (worked in Vermont at least 183 days); TB-55 names the couples it reaches (a full-year resident with a nonresident spouse who has no Vermont income), and the engine applies TB-55's conditions; when one spouse is a part-year resident and the other a nonresident: Vermont's 2025 instructions word the exception as 'only one spouse has sufficient nexus' (worked in Vermont at least 183 days); TB-55 names the couples it reaches (a full-year resident with a nonresident spouse who has no Vermont income), and the engine applies TB-55's conditions; when both spouses are nonresidents and only one has income from the state: Vermont's 2025 instructions word the exception as 'only one spouse has sufficient nexus' (worked in Vermont at least 183 days); TB-55 names the couples it reaches (a full-year resident with a nonresident spouse who has no Vermont income), and the engine applies TB-55's conditions.",
      "lines": [
        {
          "form": "PY/NR Schedule IN-113",
          "line": "couples-not-modelled",
          "description": "Married couples whose residency differs: the pairs and returns not calculated (each reason on the state page)"
        }
      ],
      "couldApply": false,
      "reason": "This is a full-year resident return (no part-year or nonresident residency given).",
      "source": {
        "url": "https://web.archive.org/web/20260203194148/http://tax.vermont.gov/sites/tax/files/documents/IN-111-Instr-2025.pdf",
        "quote": "The Vermont filing status must be the same as your federal filing status except in the following two situations where federal information may be recomputed for Vermont purposes: 1. Civil Union (available to same sex couples holding valid civil union certificates): Recomputed federal income tax information required. 2. Only one spouse has sufficient nexus to Vermont subject to Vermont’s tax jurisdiction. “Sufficient nexus” means when a spouse has worked in Vermont at least 183 days. Recomputed federal income tax information may be used. Read Technical Bulletin TB-55, Exceptions to Requirement That Vermont Filing Status Must Mirror Federal Filing Status, on our website. If you choose to file your Vermont Income Tax Return as “Married Filing Jointly,” you cannot use Schedule IN-113, Vermont Income Adjustment Calculations, Part I, to apportion income of the nonresident spouse. The credit for income tax paid to another state is available by completing Schedule IN-117, Vermont Credit for Income Tax Paid to Other State or Canadian Province."
      }
    },
    {
      "id": "VT-state-7ca2c4df",
      "category": "other",
      "description": "The charitable contribution credit (a share of contributions up to a cap, IN-111 lines 11-13) and the medical expense deduction (IN-112 line 11) need expenses and are not calculated.",
      "lines": [
        {
          "form": "IN-111",
          "line": "11-13",
          "description": "Charitable contribution credit: 5% of the first $20,000"
        },
        {
          "form": "IN-112",
          "line": "11",
          "description": "Medical expenses deduction (above the Vermont standard deduction and exemptions)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://web.archive.org/web/20260203213311id_/https://tax.vermont.gov/sites/tax/files/documents/IN-111-Instr-2025.pdf",
        "quote": "The tax credit is equal to 5% of the first $20,000 of charitable contributions"
      }
    },
    {
      "id": "VT-state-7cd8fef4",
      "category": "business",
      "description": "The IN-111 line 9 additions (Schedule IN-119, Vermont's share of the federal tax) are calculated for the federal additional tax on early IRA and employer-plan distributions; the additions for the federal tax on early HSA and MSA distributions, the Form 4972 lump-sum tax and credit recaptures are not: the inputs do not carry them (a lump sum entered as iraDistributions is taxed at the ordinary rates).",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It needs business income or adjustment details the request does not carry.",
      "source": {
        "url": "https://web.archive.org/web/20260203213311id_/https://tax.vermont.gov/sites/tax/files/documents/IN-111-Instr-2025.pdf",
        "quote": "Qualified Retirement Plan distributions including IRA, HSA & MSA - Recapture of federal Investment Tax Credit - Lump-sum Distribution from federal Form 4972"
      }
    },
    {
      "id": "VT-state-cc1843ed",
      "category": "dependent-care",
      "description": "The child tax credit is refundable and the child and dependent care credit needs expenses; neither is calculated.",
      "lines": [
        {
          "form": "IN-112",
          "line": "Part II 1-2",
          "description": "Vermont child and dependent care credit (72% of the federal credit, refundable)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://web.archive.org/web/20260203201231id_/https://tax.vermont.gov/sites/tax/files/documents/IN-112-Instr-2025.pdf",
        "quote": "Multiply Line 1 by 72% (0.72)."
      }
    }
  ],
  "stateDocs": "https://quantcalc.app/docs/state-tax/states/vt/",
  "engineVersion": "1.14.2"
}

A couple where one spouse moves first (New York)

The primary lived in New York all year; the spouse moved in on July 1, with $30,000 of the year's $60,000 of wages earned after the move. residency is the primary's own, residency.spouse the spouse's. New York's instructions say such a couple files separate returns unless both elect a joint resident return: residency.couple computes both (the primary's IT-201 and the spouse's IT-203 as married filing separately; the joint IT-201), applies the default and names the lowest. Engine 1.13.0.

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "NY",
  "filingStatus": "mfj",
  "age": 63,
  "wages": 95000,
  "iraDistributions": 12000,
  "spouse": {
    "age": 61,
    "wages": 60000
  },
  "residency": {
    "status": "resident",
    "spouse": {
      "status": "partYear",
      "residentFrom": "2026-07-01",
      "residentTo": "2026-12-31",
      "stateIncome": {
        "wages": 30000
      }
    }
  }
}

Returns tax $5,887.35 (effective rate 3.5254%), engine version 1.14.2.

The complete response

{
  "state": "NY",
  "stateName": "New York",
  "tax": 5887.35,
  "effectiveRate": 0.03525359281437125,
  "totalTax": 5887.35,
  "refundableCredits": {
    "total": 0,
    "items": []
  },
  "netTax": 5887.35,
  "residency": {
    "status": "resident",
    "method": "resident",
    "methodText": "a full-year resident return",
    "couple": {
      "pair": "RP",
      "rule": "when one spouse is a full-year resident and the other a part-year resident, NY: separate returns, unless the couple elects a joint resident return (both taxed as full-year residents)",
      "options": [
        {
          "treatment": "separate",
          "tax": 5887.35,
          "totalTax": 5887.35,
          "netTax": 5887.35,
          "returns": [
            {
              "return": "primary",
              "filingStatus": "mfs",
              "residency": "resident",
              "method": "resident",
              "filed": true,
              "tax": 4565.65,
              "netTax": 4565.65,
              "taxableIncome": 87000
            },
            {
              "return": "spouse",
              "filingStatus": "mfs",
              "residency": "partYear",
              "method": "R",
              "form": "IT-203",
              "filed": true,
              "tax": 1321.7,
              "netTax": 1321.7,
              "taxableIncome": 52000,
              "ratio": 0.5
            }
          ]
        },
        {
          "treatment": "jointAsResidents",
          "tax": 7485.6722,
          "totalTax": 7485.6722,
          "netTax": 7485.6722,
          "returns": [
            {
              "return": "joint",
              "filingStatus": "mfj",
              "residency": "resident",
              "method": "resident",
              "filed": true,
              "tax": 7485.6722,
              "netTax": 7485.6722,
              "taxableIncome": 138950
            }
          ]
        }
      ],
      "applied": "separate",
      "appliedBecause": "the state's default when the couple makes no election",
      "lowest": "separate",
      "breakdownIs": "the primary's separate return"
    }
  },
  "input": {
    "filingStatus": "mfj",
    "age": 63,
    "ordinaryIncome": 0,
    "socialSecurity": 0,
    "capitalGains": 0,
    "wages": 95000,
    "iraDistributions": 12000,
    "residency": {
      "status": "resident",
      "stateIncome": {},
      "spouse": {
        "status": "partYear",
        "residentFromDay": 182,
        "residentToDay": 365,
        "stateIncome": {
          "wages": 30000
        }
      }
    },
    "spouse": {
      "age": 61,
      "wages": 60000,
      "iraDistributions": 0,
      "pensionPrivate": 0,
      "pensionPublic": 0,
      "pensionMilitary": 0,
      "rothConversion": 0
    }
  },
  "rules": {
    "taxesSocialSecurity": false,
    "socialSecurityRule": "exempt",
    "bracketCount": 9,
    "standardDeduction": 16050,
    "personalExemption": 0,
    "seniorSubtraction": 0,
    "seniorSubtractionMinAge": 0,
    "capitalGainsTaxedAsOrdinary": true,
    "capitalGainsInclusionRatio": 1,
    "retirementIncomeExclusion": {
      "cap": 40000,
      "minAge": 59,
      "partialCap": 0,
      "partialMinAge": 0,
      "incomeLimit": 0,
      "reducedBySocialSecurity": false
    },
    "militaryRetirement": {
      "treatment": "exempt",
      "cap": null,
      "minAge": 0,
      "capBelowMinAge": null,
      "percentExempt": null,
      "incomeLimit": null,
      "incomeLimitPhaseoutRange": null,
      "sharesGeneralExclusion": true,
      "earnedIncomeBonus": null,
      "earnedIncomeThreshold": null,
      "reducedBySocialSecurity": false,
      "creditRate": null,
      "perTaxpayer": true
    },
    "wages": {
      "treatment": "ordinary_income",
      "earnedIncomeInRetirementExclusion": null
    },
    "localTax": {
      "included": false,
      "rate": null,
      "basis": "none"
    },
    "sources": {
      "rates": [
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105 Estimated Income Tax Payment Voucher for Individuals (2026)",
          "kind": "instructions",
          "official": true,
          "quote": "IT-2105-I (2026)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.irs.gov/newsroom/irs-releases-tax-inflation-adjustments-for-tax-year-2026-including-amendments-from-the-one-big-beautiful-bill",
          "title": "Irs releases tax inflation adjustments for tax year 2026 including amendments from the one big beautiful bill",
          "kind": "legislation",
          "official": true,
          "quote": "for heads of households, the standard deduction will be $24,150",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "2025 IT-201 instructions",
          "kind": "instructions",
          "official": true,
          "quote": "Married filing separate return",
          "checked": "2026-10-12"
        }
      ],
      "deductions": [
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105 Estimated Income Tax Payment Voucher for Individuals (2026)",
          "kind": "instructions",
          "official": true,
          "quote": "Single and you cannot be claimed as a dependent on another taxpayer",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.irs.gov/newsroom/irs-releases-tax-inflation-adjustments-for-tax-year-2026-including-amendments-from-the-one-big-beautiful-bill",
          "title": "Irs releases tax inflation adjustments for tax year 2026 including amendments from the one big beautiful bill",
          "kind": "legislation",
          "official": true,
          "quote": "for heads of households, the standard deduction will be $24,150",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "New York State Department of Taxation and Finance: it201i_2025.pdf",
          "kind": "instructions",
          "official": true,
          "quote": "Use New York State household credit table 2.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it221i_2025.pdf",
          "title": "New York State Department of Taxation and Finance: it221i_2025.pdf",
          "kind": "instructions",
          "official": true,
          "quote": "Generally, the most you can exclude is $5,200.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it215_2025_fill_in.pdf",
          "title": "Form IT-215 (2025) Claim for Earned Income Credit",
          "kind": "instructions",
          "official": true,
          "quote": "New York State earned income credit (NYS EIC) rate 30% (.30)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it215i_2025.pdf",
          "title": "Instructions for Form IT-215 (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Line 2: If your investment income is more than $11,950, you cannot",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201_2025_fill_in.pdf",
          "title": "Form IT-201 (2025) Resident Income Tax Return",
          "kind": "instructions",
          "official": true,
          "quote": "Payments and refundable credits 63 Empire State child credit",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it214_2025_fill_in.pdf",
          "title": "Form IT-214 (2025) Claim for Real Property Tax Credit",
          "kind": "instructions",
          "official": true,
          "quote": "If line 8 is more than $18,000, stop; you do not qualify for this credit.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it214i_2025.pdf",
          "title": "Instructions for Form IT-214 (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "the credit can be as much as $375.",
          "checked": "2026-10-12"
        }
      ],
      "retirement_income": [
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "Instructions for Form IT-201 Full-Year Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Line 29: Pension and annuity income exclusion",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201_2025_fill_in.pdf",
          "title": "Form IT-201 Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Taxable amount of IRA distributions",
          "checked": "2026-10-12"
        }
      ],
      "local_tax": [
        {
          "url": "https://web.archive.org/web/20251107162049/https://www.nysenate.gov/legislation/laws/TAX/1303",
          "title": "NY Tax Law § 1303. City taxable income (Wayback copy of nysenate.gov; live site Cloudflare-blocked)",
          "kind": "statute",
          "official": true,
          "quote": "The city taxable income of a city resident individual shall mean and be the same as his or her New York taxable income",
          "checked": "2026-10-01"
        },
        {
          "url": "https://web.archive.org/web/20251114213033/https://www.nysenate.gov/legislation/laws/TAX/1302",
          "title": "NY Tax Law § 1302. Persons subject to tax (Wayback copy)",
          "kind": "statute",
          "official": true,
          "quote": "imposed for each taxable year on the city taxable income of every city resident individual, estate and trust",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20251209112301/https://www.nysenate.gov/legislation/laws/TAX/1305",
          "title": "NY Tax Law § 1305. City resident and city nonresident defined (Wayback copy)",
          "kind": "statute",
          "official": true,
          "quote": "who is domiciled in the city wherein the tax is imposed",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105, Estimated Income Tax Payment Voucher for Individuals (IT-2105-I, 2026)",
          "kind": "instructions",
          "official": true,
          "quote": "Line 22a – The current rate for Yonkers is 16.75% (.1675). If you are",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/publications/withholding/nys50_t_y.pdf",
          "title": "NYS-50-T-Y (1/26) Yonkers Withholding Tax Tables and Methods, effective January 1, 2026",
          "kind": "agency_page",
          "official": true,
          "quote": "Effective January 1, 2026 – December 31, 2026",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "Instructions for Form IT-201, Full-Year Resident Income Tax Return (IT-201-I, 2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Yonkers worksheet",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it360_1i_2025.pdf",
          "title": "Instructions for Form IT-360.1 Change of City Resident Status (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Enter in Column B that part of the income included in Column A\nthat you received from all sources while you were a New York\nCity resident.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "Instructions for Form IT-201 Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Table 2 - Part-year New York City residents:\nNew York City school tax credit proration chart",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it215i_2025.pdf",
          "title": "Instructions for Form IT-215 Claim for Earned Income Credit (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "9 Part-year NYC resident EIC (multiply line 5 by line 8). Enter this amount on\n\t\t  Form IT-215, line 27; and on Form IT-201, line 70, or on Form IT-203-ATT, line 11.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it360_1_2025_fill_in.pdf",
          "title": "Form IT-360.1 Change of City Resident Status (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "47 New York City taxable income (subtract line 46 from line 45)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it360_1i_2025.pdf",
          "title": "Instructions for Form IT-360.1 Change of City Resident Status (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Enter in the applicable column your income percentage from the\nworksheet below.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/y203i_2025.pdf",
          "title": "Instructions for Form Y-203 Yonkers Nonresident Earnings Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "If you are married, you\ncannot file a joint Yonkers nonresident earnings tax return. If you each\nhave taxable earnings, you each must use a separate Form Y-203 to\ncalculate your tax.",
          "checked": "2026-10-12"
        }
      ],
      "surtax": [
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105 Estimated Income Tax Payment Voucher for Individuals (2026)",
          "kind": "instructions",
          "official": true,
          "quote": "If your NYAGI is more than $107,650",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "It201i 2025",
          "kind": "instructions",
          "official": true,
          "quote": "and your taxable income (line 38) is $269,300 or less, then you must calculate your tax using this worksheet",
          "checked": "2026-10-12"
        }
      ],
      "residency": [
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it203i_2025.pdf",
          "title": "Instructions for Form IT-203 Nonresident and Part-Year Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "To calculate your income percentage, divide the amount from",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it203_2025_fill_in.pdf",
          "title": "Form IT-203 Nonresident and Part-Year Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "44 Base tax (subtract line 43 from line 42; if line 43 is more than line 42, enter 0)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it360_1i_2025.pdf",
          "title": "Instructions for Form IT-360.1 Change of City Resident Status (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "If you changed your New York City resident status, you have to prorate your standard deduction and your dependent exemptions.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it203i_2025.pdf",
          "title": "Instructions for Form IT-203 Nonresident and Part-Year Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "one spouse is a part-year resident and the other is a\nnonresident with New York source income, or",
          "checked": "2026-10-12"
        }
      ]
    },
    "unsourced": {}
  },
  "priorYearFigures": [],
  "local": {
    "onStateReturn": [],
    "separateReturns": [],
    "separateReturnsTax": 0,
    "total": 0
  },
  "taxYear": "2026",
  "methodology": "https://quantcalc.app/docs/state-tax-api/",
  "note": "State income tax only. Federal tax, FICA and local levies are not included. Social Security must be the FEDERALLY-TAXABLE portion, not gross benefits.",
  "perPerson": [
    {
      "role": "primary",
      "age": 63,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "exempt",
      "retirementExcluded": 12000,
      "retirementRule": "capped_exclusion",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 0,
      "seniorRule": "none"
    }
  ],
  "breakdown": {
    "taxableIncome": 87000,
    "socialSecurityInBase": 0,
    "retirementInBase": 0,
    "conversionInBase": 0,
    "capitalGainsInBase": 0,
    "militaryExcluded": 0,
    "retirementExcluded": 12000,
    "earnedIncomeExcluded": 0,
    "seniorSubtraction": 0,
    "militaryCredit": 0
  },
  "inputsNotSupplied": [],
  "notModelled": [
    {
      "id": "NY-global-9712d4d1",
      "category": "other-state-credit",
      "description": "Other-state credits: the credits for tax paid to other states (a resident's or part-year resident's credit for income tax paid to another state, country or locality, each state's own formula) are not calculated.",
      "lines": [
        {
          "form": "IT-201",
          "line": "41",
          "description": "Resident credit (tax paid to other jurisdictions)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs income taxed by another state or locality, which the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Did you have income from sources outside New York State and pay income tax to another state, a local government"
      }
    },
    {
      "id": "NY-global-fd1da389",
      "category": "dependent-care",
      "description": "Dependents: the dependents input (each dependent's age, and whether a student or disabled) applies every nonrefundable dependent exemption, deduction and credit each state page lists (engine 1.7.0), and counts the qualifying children of the earned income credits (engine 1.12.0). Not calculated: refundable child tax credits and other refundable credits a state page does not list, credits that need expenses (child and dependent care, education) and facts the input does not carry (adoption, custody, certification); each state page lists its own.",
      "lines": [
        {
          "form": "IT-201",
          "line": "64",
          "description": "NYS / NYC child and dependent care credit"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Line 64: New York State and New York City child and dependent care credits"
      }
    },
    {
      "id": "NY-locality-a5a85a47",
      "category": "dependent-care",
      "description": "The NYC child and dependent care credit (needs expenses).",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it216i_2025.pdf",
        "quote": "as 75% of the New York State child and dependent care credit,"
      }
    },
    {
      "id": "NY-state-43f9c9a6",
      "category": "business",
      "description": "The NYC taxes on lump-sum and accumulation distributions and the NYC unincorporated business tax credit (IT-201 lines 51 and 53) are not calculated.",
      "lines": [
        {
          "form": "IT-201",
          "line": "51-53",
          "description": "Other NYC taxes (lump-sum and accumulation distributions) and NYC nonrefundable credits (UBT credit)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs business income or adjustment details the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Can you claim the New York City unincorporated business"
      }
    },
    {
      "id": "NY-state-7b1c5618",
      "category": "other",
      "description": "The Empire State child credit is refundable and is not calculated.",
      "lines": [
        {
          "form": "IT-201",
          "line": "63",
          "description": "Empire State child credit (refundable)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "If you qualify, complete Form IT-213, and transfer the amount from Form IT-213 to Form IT-201, line 63."
      }
    },
    {
      "id": "NY-state-af0829b6",
      "category": "other",
      "description": "The NYC income tax elimination credit (IT-201 line 70a, for NYC residents at low income) is not calculated; the NYC earned income credit and the NYC school tax credits are (refundableCredits, with an NY-NYC locality, engine 1.12.0). The real property tax credit (IT-214) reads rentPaid as adjusted rent (rent less any rent subsidy) and, with rentIncludesHeat, applies the form's adjustment for rent that includes heat; rent that also includes gas, electricity or furnishings, which the form adjusts further, is not an input.",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Line 70a: New York City income tax elimination credit"
      }
    },
    {
      "id": "NY-state-e41aa725",
      "category": "locality",
      "description": "A part-year New York City resident's NYC earned income credit (IT-215 Worksheet C, the period's income percentage) is not calculated: refundableCredits and netTax leave it out on a part-year NYC return. The NYC school tax credits are (engine 1.13.1: the fixed amount from the Table 2 proration chart, the rate-reduction amount on IT-360.1 line 47; IT-201 lines 69 and 69a, or IT-203 lines 60 and 60a for a part-year state resident).",
      "lines": [
        {
          "form": "IT-201",
          "line": "70 (part-year NYC)",
          "description": "A part-year NYC resident's NYC earned income credit (IT-215 Worksheet C line 9, line 70); the part-year NYC school tax credits (lines 69 and 69a, Table 2 and IT-360.1 line 47) are calculated (engine 1.13.1)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It depends on where the household lives or works: the engine covers the jurisdictions of its locality registry only.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Table 2 - Part-year New York City residents: New York City school tax credit proration chart"
      }
    },
    {
      "id": "NY-state-ed2572ea",
      "category": "other",
      "description": "The pension and annuity exclusion of a beneficiary under 59 (allowed when the person who died would have been 59 and a half) is not calculated: the engine reads a decedent's age only for South Carolina's surviving-spouse deduction (deceasedSpouseAge), so a survivor under 59 gets none here.",
      "lines": [
        {
          "form": "IT-201",
          "line": "29 beneficiary",
          "description": "Line 29 for a beneficiary: allowed when the decedent would have been 59½, whatever the beneficiary's age"
        },
        {
          "form": "statute",
          "line": "IT-201-I line 29 Beneficiaries",
          "description": "Pension exclusion of a beneficiary follows the decedent's age"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "if the decedent would have been entitled to it, had the decedent continued to live, regardless of your age"
      }
    },
    {
      "id": "NY-state-fc6a47aa",
      "category": "other",
      "description": "The disability income exclusion's combined limit with the pension exclusion is not applied (it binds only when a person under 65 has disability pay and more other excluded pension income than the exclusion leaves), and on a married-filing-separately return none is given (it needs the spouses to have lived apart).",
      "lines": [
        {
          "form": "IT-221",
          "line": "MFS / combined limit",
          "description": "IT-221 on a separate return (spouses lived apart all year) and the combined limit with the pension exclusion"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it221i_2025.pdf",
        "quote": "The total of your disability income exclusion and any pension and annuity income exclusion you claim cannot exceed $20,000."
      }
    }
  ],
  "stateDocs": "https://quantcalc.app/docs/state-tax/states/ny/",
  "engineVersion": "1.14.2"
}

A part-year New York City resident (New York, IT-360.1)

A couple who moved into New York City on April 1 and lived in New York State all year: the IT-201 for the state, and the part-year NYC resident tax of Form IT-360.1 Part 4 on the $90,000 received while in the city, the standard deduction prorated by the Proration chart (nine months: $12,038 of $16,050). The NYC line carries partYear. Engine 1.13.0.

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "NY",
  "filingStatus": "mfj",
  "age": 45,
  "wages": 120000,
  "localities": [
    {
      "code": "NY-NYC",
      "residentFrom": "2026-04-01",
      "residentTo": "2026-12-31",
      "residentIncome": {
        "wages": 90000
      }
    }
  ]
}

Returns tax $8,166.83 (effective rate 6.8057%), engine version 1.14.2.

The complete response

{
  "state": "NY",
  "stateName": "New York",
  "tax": 8166.82698,
  "effectiveRate": 0.0680568915,
  "totalTax": 8166.82698,
  "refundableCredits": {
    "total": 259.50536,
    "items": [
      {
        "id": "nyc-school-tax-credit",
        "name": "NYC school tax credit (fixed amount)",
        "form": "IT-201 line 69 (Table 2) / IT-203 line 60",
        "amount": 94,
        "valueYear": 2026
      },
      {
        "id": "nyc-school-tax-credit-rate-reduction",
        "name": "NYC school tax credit (rate reduction)",
        "form": "IT-201 line 69a (IT-360.1 line 47) / IT-203 line 60a",
        "amount": 165.50536,
        "valueYear": 2026
      }
    ]
  },
  "netTax": 7907.32162,
  "input": {
    "filingStatus": "mfj",
    "age": 45,
    "ordinaryIncome": 0,
    "socialSecurity": 0,
    "capitalGains": 0,
    "wages": 120000,
    "localities": [
      {
        "code": "NY-NYC",
        "role": "resident"
      }
    ]
  },
  "rules": {
    "taxesSocialSecurity": false,
    "socialSecurityRule": "exempt",
    "bracketCount": 9,
    "standardDeduction": 16050,
    "personalExemption": 0,
    "seniorSubtraction": 0,
    "seniorSubtractionMinAge": 0,
    "capitalGainsTaxedAsOrdinary": true,
    "capitalGainsInclusionRatio": 1,
    "retirementIncomeExclusion": {
      "cap": 40000,
      "minAge": 59,
      "partialCap": 0,
      "partialMinAge": 0,
      "incomeLimit": 0,
      "reducedBySocialSecurity": false
    },
    "militaryRetirement": {
      "treatment": "exempt",
      "cap": null,
      "minAge": 0,
      "capBelowMinAge": null,
      "percentExempt": null,
      "incomeLimit": null,
      "incomeLimitPhaseoutRange": null,
      "sharesGeneralExclusion": true,
      "earnedIncomeBonus": null,
      "earnedIncomeThreshold": null,
      "reducedBySocialSecurity": false,
      "creditRate": null,
      "perTaxpayer": true
    },
    "wages": {
      "treatment": "ordinary_income",
      "earnedIncomeInRetirementExclusion": null
    },
    "localTax": {
      "included": false,
      "rate": null,
      "basis": "none"
    },
    "sources": {
      "rates": [
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105 Estimated Income Tax Payment Voucher for Individuals (2026)",
          "kind": "instructions",
          "official": true,
          "quote": "IT-2105-I (2026)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.irs.gov/newsroom/irs-releases-tax-inflation-adjustments-for-tax-year-2026-including-amendments-from-the-one-big-beautiful-bill",
          "title": "Irs releases tax inflation adjustments for tax year 2026 including amendments from the one big beautiful bill",
          "kind": "legislation",
          "official": true,
          "quote": "for heads of households, the standard deduction will be $24,150",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "2025 IT-201 instructions",
          "kind": "instructions",
          "official": true,
          "quote": "Married filing separate return",
          "checked": "2026-10-12"
        }
      ],
      "deductions": [
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105 Estimated Income Tax Payment Voucher for Individuals (2026)",
          "kind": "instructions",
          "official": true,
          "quote": "Single and you cannot be claimed as a dependent on another taxpayer",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.irs.gov/newsroom/irs-releases-tax-inflation-adjustments-for-tax-year-2026-including-amendments-from-the-one-big-beautiful-bill",
          "title": "Irs releases tax inflation adjustments for tax year 2026 including amendments from the one big beautiful bill",
          "kind": "legislation",
          "official": true,
          "quote": "for heads of households, the standard deduction will be $24,150",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "New York State Department of Taxation and Finance: it201i_2025.pdf",
          "kind": "instructions",
          "official": true,
          "quote": "Use New York State household credit table 2.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it221i_2025.pdf",
          "title": "New York State Department of Taxation and Finance: it221i_2025.pdf",
          "kind": "instructions",
          "official": true,
          "quote": "Generally, the most you can exclude is $5,200.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it215_2025_fill_in.pdf",
          "title": "Form IT-215 (2025) Claim for Earned Income Credit",
          "kind": "instructions",
          "official": true,
          "quote": "New York State earned income credit (NYS EIC) rate 30% (.30)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it215i_2025.pdf",
          "title": "Instructions for Form IT-215 (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Line 2: If your investment income is more than $11,950, you cannot",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201_2025_fill_in.pdf",
          "title": "Form IT-201 (2025) Resident Income Tax Return",
          "kind": "instructions",
          "official": true,
          "quote": "Payments and refundable credits 63 Empire State child credit",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it214_2025_fill_in.pdf",
          "title": "Form IT-214 (2025) Claim for Real Property Tax Credit",
          "kind": "instructions",
          "official": true,
          "quote": "If line 8 is more than $18,000, stop; you do not qualify for this credit.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it214i_2025.pdf",
          "title": "Instructions for Form IT-214 (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "the credit can be as much as $375.",
          "checked": "2026-10-12"
        }
      ],
      "local_tax": [
        {
          "url": "https://web.archive.org/web/20251107162049/https://www.nysenate.gov/legislation/laws/TAX/1303",
          "title": "NY Tax Law § 1303. City taxable income (Wayback copy of nysenate.gov; live site Cloudflare-blocked)",
          "kind": "statute",
          "official": true,
          "quote": "The city taxable income of a city resident individual shall mean and be the same as his or her New York taxable income",
          "checked": "2026-10-01"
        },
        {
          "url": "https://web.archive.org/web/20251114213033/https://www.nysenate.gov/legislation/laws/TAX/1302",
          "title": "NY Tax Law § 1302. Persons subject to tax (Wayback copy)",
          "kind": "statute",
          "official": true,
          "quote": "imposed for each taxable year on the city taxable income of every city resident individual, estate and trust",
          "checked": "2026-10-12"
        },
        {
          "url": "https://web.archive.org/web/20251209112301/https://www.nysenate.gov/legislation/laws/TAX/1305",
          "title": "NY Tax Law § 1305. City resident and city nonresident defined (Wayback copy)",
          "kind": "statute",
          "official": true,
          "quote": "who is domiciled in the city wherein the tax is imposed",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105, Estimated Income Tax Payment Voucher for Individuals (IT-2105-I, 2026)",
          "kind": "instructions",
          "official": true,
          "quote": "Line 22a – The current rate for Yonkers is 16.75% (.1675). If you are",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/publications/withholding/nys50_t_y.pdf",
          "title": "NYS-50-T-Y (1/26) Yonkers Withholding Tax Tables and Methods, effective January 1, 2026",
          "kind": "agency_page",
          "official": true,
          "quote": "Effective January 1, 2026 – December 31, 2026",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "Instructions for Form IT-201, Full-Year Resident Income Tax Return (IT-201-I, 2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Yonkers worksheet",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it360_1i_2025.pdf",
          "title": "Instructions for Form IT-360.1 Change of City Resident Status (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Enter in Column B that part of the income included in Column A\nthat you received from all sources while you were a New York\nCity resident.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "Instructions for Form IT-201 Resident Income Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Table 2 - Part-year New York City residents:\nNew York City school tax credit proration chart",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it215i_2025.pdf",
          "title": "Instructions for Form IT-215 Claim for Earned Income Credit (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "9 Part-year NYC resident EIC (multiply line 5 by line 8). Enter this amount on\n\t\t  Form IT-215, line 27; and on Form IT-201, line 70, or on Form IT-203-ATT, line 11.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it360_1_2025_fill_in.pdf",
          "title": "Form IT-360.1 Change of City Resident Status (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "47 New York City taxable income (subtract line 46 from line 45)",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it360_1i_2025.pdf",
          "title": "Instructions for Form IT-360.1 Change of City Resident Status (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "Enter in the applicable column your income percentage from the\nworksheet below.",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/y203i_2025.pdf",
          "title": "Instructions for Form Y-203 Yonkers Nonresident Earnings Tax Return (2025)",
          "kind": "instructions",
          "official": true,
          "quote": "If you are married, you\ncannot file a joint Yonkers nonresident earnings tax return. If you each\nhave taxable earnings, you each must use a separate Form Y-203 to\ncalculate your tax.",
          "checked": "2026-10-12"
        }
      ],
      "surtax": [
        {
          "url": "https://www.tax.ny.gov/pdf/2026/inc/it2105i_2026.pdf",
          "title": "Instructions for Form IT-2105 Estimated Income Tax Payment Voucher for Individuals (2026)",
          "kind": "instructions",
          "official": true,
          "quote": "If your NYAGI is more than $107,650",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
          "title": "It201i 2025",
          "kind": "instructions",
          "official": true,
          "quote": "and your taxable income (line 38) is $269,300 or less, then you must calculate your tax using this worksheet",
          "checked": "2026-10-12"
        }
      ]
    },
    "unsourced": {}
  },
  "priorYearFigures": [],
  "local": {
    "onStateReturn": [
      {
        "code": "NY-NYC",
        "name": "New York City",
        "kind": "ny-nyc",
        "role": "resident",
        "form": "IT-201 lines 47-54 (and 69-70a refundable)",
        "base": 77962,
        "rate": 0,
        "grossTax": 2803.97478,
        "credits": 0,
        "tax": 2803.97478,
        "valueYear": 2026,
        "partYear": {
          "residentFrom": "2026-04-01",
          "residentTo": "2026-12-31",
          "months": 9,
          "proration": 0.75,
          "method": "IT-360.1 Part 4: the resident period's New York AGI less the standard deduction and dependent exemptions by full months (more than half a month counts), the household credit x full months / 12"
        }
      }
    ],
    "separateReturns": [],
    "separateReturnsTax": 0,
    "total": 2803.97478
  },
  "taxYear": "2026",
  "methodology": "https://quantcalc.app/docs/state-tax-api/",
  "note": "State income tax only. Federal tax, FICA and local levies are not included. Social Security must be the FEDERALLY-TAXABLE portion, not gross benefits.",
  "perPerson": [
    {
      "role": "household",
      "age": 45,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "exempt",
      "retirementExcluded": 0,
      "retirementRule": "capped_exclusion",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 0,
      "seniorRule": "none"
    }
  ],
  "breakdown": {
    "taxableIncome": 103950,
    "socialSecurityInBase": 0,
    "retirementInBase": 0,
    "conversionInBase": 0,
    "capitalGainsInBase": 0,
    "militaryExcluded": 0,
    "retirementExcluded": 0,
    "earnedIncomeExcluded": 0,
    "seniorSubtraction": 0,
    "militaryCredit": 0
  },
  "inputsNotSupplied": [],
  "notModelled": [
    {
      "id": "NY-global-9712d4d1",
      "category": "other-state-credit",
      "description": "Other-state credits: the credits for tax paid to other states (a resident's or part-year resident's credit for income tax paid to another state, country or locality, each state's own formula) are not calculated.",
      "lines": [
        {
          "form": "IT-201",
          "line": "41",
          "description": "Resident credit (tax paid to other jurisdictions)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs income taxed by another state or locality, which the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Did you have income from sources outside New York State and pay income tax to another state, a local government"
      }
    },
    {
      "id": "NY-global-fd1da389",
      "category": "dependent-care",
      "description": "Dependents: the dependents input (each dependent's age, and whether a student or disabled) applies every nonrefundable dependent exemption, deduction and credit each state page lists (engine 1.7.0), and counts the qualifying children of the earned income credits (engine 1.12.0). Not calculated: refundable child tax credits and other refundable credits a state page does not list, credits that need expenses (child and dependent care, education) and facts the input does not carry (adoption, custody, certification); each state page lists its own.",
      "lines": [
        {
          "form": "IT-201",
          "line": "64",
          "description": "NYS / NYC child and dependent care credit"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Line 64: New York State and New York City child and dependent care credits"
      }
    },
    {
      "id": "NY-locality-a5a85a47",
      "category": "dependent-care",
      "description": "The NYC child and dependent care credit (needs expenses).",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it216i_2025.pdf",
        "quote": "as 75% of the New York State child and dependent care credit,"
      }
    },
    {
      "id": "NY-state-43f9c9a6",
      "category": "business",
      "description": "The NYC taxes on lump-sum and accumulation distributions and the NYC unincorporated business tax credit (IT-201 lines 51 and 53) are not calculated.",
      "lines": [
        {
          "form": "IT-201",
          "line": "51-53",
          "description": "Other NYC taxes (lump-sum and accumulation distributions) and NYC nonrefundable credits (UBT credit)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs business income or adjustment details the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Can you claim the New York City unincorporated business"
      }
    },
    {
      "id": "NY-state-7b1c5618",
      "category": "other",
      "description": "The Empire State child credit is refundable and is not calculated.",
      "lines": [
        {
          "form": "IT-201",
          "line": "63",
          "description": "Empire State child credit (refundable)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "If you qualify, complete Form IT-213, and transfer the amount from Form IT-213 to Form IT-201, line 63."
      }
    },
    {
      "id": "NY-state-af0829b6",
      "category": "other",
      "description": "The NYC income tax elimination credit (IT-201 line 70a, for NYC residents at low income) is not calculated; the NYC earned income credit and the NYC school tax credits are (refundableCredits, with an NY-NYC locality, engine 1.12.0). The real property tax credit (IT-214) reads rentPaid as adjusted rent (rent less any rent subsidy) and, with rentIncludesHeat, applies the form's adjustment for rent that includes heat; rent that also includes gas, electricity or furnishings, which the form adjusts further, is not an input.",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Line 70a: New York City income tax elimination credit"
      }
    },
    {
      "id": "NY-state-e41aa725",
      "category": "locality",
      "description": "A part-year New York City resident's NYC earned income credit (IT-215 Worksheet C, the period's income percentage) is not calculated: refundableCredits and netTax leave it out on a part-year NYC return. The NYC school tax credits are (engine 1.13.1: the fixed amount from the Table 2 proration chart, the rate-reduction amount on IT-360.1 line 47; IT-201 lines 69 and 69a, or IT-203 lines 60 and 60a for a part-year state resident).",
      "lines": [
        {
          "form": "IT-201",
          "line": "70 (part-year NYC)",
          "description": "A part-year NYC resident's NYC earned income credit (IT-215 Worksheet C line 9, line 70); the part-year NYC school tax credits (lines 69 and 69a, Table 2 and IT-360.1 line 47) are calculated (engine 1.13.1)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It depends on where the household lives or works: the engine covers the jurisdictions of its locality registry only.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "Table 2 - Part-year New York City residents: New York City school tax credit proration chart"
      }
    },
    {
      "id": "NY-state-ed2572ea",
      "category": "other",
      "description": "The pension and annuity exclusion of a beneficiary under 59 (allowed when the person who died would have been 59 and a half) is not calculated: the engine reads a decedent's age only for South Carolina's surviving-spouse deduction (deceasedSpouseAge), so a survivor under 59 gets none here.",
      "lines": [
        {
          "form": "IT-201",
          "line": "29 beneficiary",
          "description": "Line 29 for a beneficiary: allowed when the decedent would have been 59½, whatever the beneficiary's age"
        },
        {
          "form": "statute",
          "line": "IT-201-I line 29 Beneficiaries",
          "description": "Pension exclusion of a beneficiary follows the decedent's age"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf",
        "quote": "if the decedent would have been entitled to it, had the decedent continued to live, regardless of your age"
      }
    },
    {
      "id": "NY-state-fc6a47aa",
      "category": "other",
      "description": "The disability income exclusion's combined limit with the pension exclusion is not applied (it binds only when a person under 65 has disability pay and more other excluded pension income than the exclusion leaves), and on a married-filing-separately return none is given (it needs the spouses to have lived apart).",
      "lines": [
        {
          "form": "IT-221",
          "line": "MFS / combined limit",
          "description": "IT-221 on a separate return (spouses lived apart all year) and the combined limit with the pension exclusion"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.tax.ny.gov/pdf/2025/inc/it221i_2025.pdf",
        "quote": "The total of your disability income exclusion and any pension and annuity income exclusion you claim cannot exceed $20,000."
      }
    }
  ],
  "stateDocs": "https://quantcalc.app/docs/state-tax/states/ny/",
  "engineVersion": "1.14.2"
}

A qualifying surviving spouse (New Jersey)

filingStatus qss: one person on the return, taxed with the state's own treatment of the status, with a dependent child and a survivor pension. rules.bracketCount and rules.standardDeduction show the schedule and exemption the engine used.

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "NJ",
  "filingStatus": "qss",
  "age": 57,
  "wages": 88000,
  "survivorBenefits": true,
  "pensionPublic": 14000,
  "dependents": [
    {
      "age": 12
    }
  ]
}

Returns tax $2,722.38 (effective rate 2.669%), engine version 1.14.2.

The complete response

{
  "state": "NJ",
  "stateName": "New Jersey",
  "tax": 2722.375,
  "effectiveRate": 0.026689950980392157,
  "totalTax": 2722.375,
  "refundableCredits": {
    "total": 0,
    "items": []
  },
  "netTax": 2722.375,
  "input": {
    "filingStatus": "qss",
    "age": 57,
    "ordinaryIncome": 0,
    "socialSecurity": 0,
    "capitalGains": 0,
    "wages": 88000,
    "pensionPublic": 14000,
    "survivorBenefits": true,
    "dependents": [
      {
        "age": 12,
        "student": false,
        "disabled": false
      }
    ]
  },
  "rules": {
    "taxesSocialSecurity": false,
    "socialSecurityRule": "exempt",
    "bracketCount": 8,
    "standardDeduction": 1000,
    "personalExemption": 0,
    "seniorSubtraction": 1000,
    "seniorSubtractionMinAge": 65,
    "capitalGainsTaxedAsOrdinary": true,
    "capitalGainsInclusionRatio": 1,
    "retirementIncomeExclusion": {
      "cap": 75000,
      "minAge": 62,
      "partialCap": 0,
      "partialMinAge": 0,
      "incomeLimit": 0,
      "reducedBySocialSecurity": false
    },
    "militaryRetirement": {
      "treatment": "exempt",
      "cap": null,
      "minAge": 0,
      "capBelowMinAge": null,
      "percentExempt": null,
      "incomeLimit": null,
      "incomeLimitPhaseoutRange": null,
      "sharesGeneralExclusion": true,
      "earnedIncomeBonus": null,
      "earnedIncomeThreshold": null,
      "reducedBySocialSecurity": false,
      "creditRate": null,
      "perTaxpayer": true
    },
    "wages": {
      "treatment": "ordinary_income",
      "earnedIncomeInRetirementExclusion": null
    },
    "localTax": {
      "included": false,
      "rate": null,
      "basis": "none"
    },
    "sources": {
      "rates": [
        {
          "url": "https://www.nj.gov/treasury/taxation/pdf/current/1040i.pdf",
          "title": "2025 Form NJ-1040 Instructions (Tax Rate Schedules, p.63)",
          "kind": "instructions",
          "official": true,
          "quote": "Over $ 0 $ 20,000 $ 35,000 $ 40,000 $ 75,000 $ 500,000 $1,000,000",
          "checked": "2026-10-12"
        }
      ],
      "deductions": [
        {
          "url": "https://www.nj.gov/treasury/taxation/pdf/current/1040i.pdf",
          "title": "2025 Form NJ-1040 Instructions",
          "kind": "instructions",
          "official": true,
          "quote": "You can claim a $1,000 exemption for yourself and your spouse/CU partner",
          "checked": "2026-10-12"
        }
      ],
      "senior": [
        {
          "url": "https://www.nj.gov/treasury/taxation/pdf/current/1040i.pdf",
          "title": "1040i",
          "kind": "instructions",
          "official": true,
          "quote": "Line 7 - Senior 65+ You can claim a $1,000 exemption if you were 65 or older on the last day of the tax year",
          "checked": "2026-10-12"
        }
      ],
      "retirement_income": [
        {
          "url": "https://www.nj.gov/treasury/taxation/njit7.shtml",
          "title": "Retirement Income Exclusions",
          "kind": "agency_page",
          "official": true,
          "quote": "were 62 or older or disabled as defined by Social Security guidelines",
          "checked": "2026-10-12"
        },
        {
          "url": "https://www.nj.gov/treasury/taxation/pdf/current/1040i.pdf",
          "title": "2025 Form NJ-1040 Instructions (Line 28a Pension/Retirement Exclusion)",
          "kind": "instructions",
          "official": true,
          "quote": "were age 62 or older or blind/disabled",
          "checked": "2026-10-12"
        }
      ],
      "public_pension": [
        {
          "url": "https://www.nj.gov/treasury/taxation/pdf/current/1040i.pdf",
          "title": "2025 Form NJ-1040 Instructions (Line 20a)",
          "kind": "instructions",
          "official": true,
          "quote": "Retirement income such as pensions, annuities, and certain IRA withdrawals is taxable in New Jersey",
          "checked": "2026-10-12"
        }
      ]
    },
    "unsourced": {}
  },
  "priorYearFigures": [],
  "local": {
    "onStateReturn": [],
    "separateReturns": [],
    "separateReturnsTax": 0,
    "total": 0
  },
  "taxYear": "2026",
  "methodology": "https://quantcalc.app/docs/state-tax-api/",
  "note": "State income tax only. Federal tax, FICA and local levies are not included. Social Security must be the FEDERALLY-TAXABLE portion, not gross benefits.",
  "perPerson": [
    {
      "role": "primary",
      "age": 57,
      "militaryPay": 0,
      "militaryExcluded": 0,
      "militaryRule": "exempt",
      "retirementExcluded": 0,
      "retirementRule": "capped_exclusion",
      "earnedIncomeExcluded": 0,
      "seniorSubtraction": 0,
      "seniorRule": "senior_subtraction"
    }
  ],
  "breakdown": {
    "taxableIncome": 99500,
    "socialSecurityInBase": 0,
    "retirementInBase": 14000,
    "conversionInBase": 0,
    "capitalGainsInBase": 0,
    "militaryExcluded": 0,
    "retirementExcluded": 0,
    "earnedIncomeExcluded": 0,
    "seniorSubtraction": 0,
    "militaryCredit": 0
  },
  "inputsNotSupplied": [
    {
      "input": "blind",
      "family": "blind_disability",
      "assumed": "not blind",
      "probed": "true",
      "taxMin": 2377.0625,
      "taxMax": 2722.375,
      "totalTaxMin": 2377.0625,
      "totalTaxMax": 2722.375,
      "netTaxMin": 2377.0625,
      "netTaxMax": 2722.375
    },
    {
      "input": "disabled",
      "family": "blind_disability",
      "assumed": "not disabled",
      "probed": "true",
      "taxMin": 2377.0625,
      "taxMax": 2722.375,
      "totalTaxMin": 2377.0625,
      "totalTaxMax": 2722.375,
      "netTaxMin": 2377.0625,
      "netTaxMax": 2722.375
    },
    {
      "input": "propertyTaxPaid",
      "family": "deductions",
      "assumed": "no property tax paid on the home (no property-tax credit or deduction)",
      "probed": "$2,000 and $8,000",
      "taxMin": 2280.375,
      "taxMax": 2722.375,
      "totalTaxMin": 2280.375,
      "totalTaxMax": 2722.375,
      "netTaxMin": 2280.375,
      "netTaxMax": 2722.375
    },
    {
      "input": "rentPaid",
      "family": "deductions",
      "assumed": "no rent paid for the home (no renter's credit)",
      "probed": "$6,000 and $18,000",
      "taxMin": 2543.365,
      "taxMax": 2722.375,
      "totalTaxMin": 2543.365,
      "totalTaxMax": 2722.375,
      "netTaxMin": 2543.365,
      "netTaxMax": 2722.375
    }
  ],
  "notModelled": [
    {
      "id": "NJ-global-9712d4d1",
      "category": "other-state-credit",
      "description": "Other-state credits: the credits for tax paid to other states (a resident's or part-year resident's credit for income tax paid to another state, country or locality, each state's own formula) are not calculated.",
      "lines": [
        {
          "form": "NJ-1040",
          "line": "44-45",
          "description": "Credit for taxes paid to other jurisdictions (NJ-COJ); balance"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs income taxed by another state or locality, which the request does not carry.",
      "source": {
        "url": "https://www.nj.gov/treasury/taxation/pdf/current/1040i.pdf",
        "quote": "Income Taxed by Another Jurisdiction. If you have income"
      }
    },
    {
      "id": "NJ-locality-fcbee0a3",
      "category": "locality",
      "description": "Per-worker head taxes and employer payroll taxes: Alabama occupational taxes (Birmingham), Colorado occupational privilege taxes (Denver, Aurora, Greenwood Village, Glendale, Sheridan), the Newark payroll tax, West Virginia city service fees, the Portland Arts Tax, the TriMet and Lane transit self-employment taxes, the Pennsylvania Local Services Tax: flat or employer levies, not taxes on the household's income.",
      "lines": [],
      "couldApply": "unknown",
      "reason": "It depends on where the household lives or works: the engine covers the jurisdictions of its locality registry only.",
      "source": {
        "url": "https://www.birminghamal.gov/government/city-departments/finance/tax-license-division",
        "quote": "Lodging Tax Occupational Tax Sales Tax"
      }
    },
    {
      "id": "NJ-state-33f83d90",
      "category": "other",
      "description": "The special exclusion for filers who will never receive Social Security or Railroad Retirement benefits is not calculated: the inputs do not say that a person can never receive them.",
      "lines": [
        {
          "form": "1040i",
          "line": "28a/28b special",
          "description": "Special exclusion ($3,000 / $6,000) for filers who will never receive Social Security or Railroad Retirement benefits"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.nj.gov/treasury/taxation/pdf/current/1040i.pdf",
        "quote": "Special Exclusion. If you (and your spouse if filing jointly)"
      }
    },
    {
      "id": "NJ-state-44a89f7f",
      "category": "other",
      "description": "The part of an IRA withdrawal or pension that returns contributions New Jersey already taxed is not calculated (the NJ-1040 excludable amount on line 20b: New Jersey never allowed a deduction for IRA contributions): the whole federally taxable amount is treated as New Jersey income.",
      "lines": [
        {
          "form": "NJ-1040",
          "line": "20b",
          "description": "Excludable pension, annuity and IRA amounts (return of contributions New Jersey already taxed)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It turns on facts the request does not carry.",
      "source": {
        "url": "https://www.nj.gov/treasury/taxation/pdf/current/1040i.pdf",
        "quote": "Since you have already been taxed on your contributions, you"
      }
    },
    {
      "id": "NJ-state-6d685751",
      "category": "dependent-care",
      "description": "The New Jersey child tax credit is refundable and the dependent care credit needs expenses; neither is calculated.",
      "lines": [
        {
          "form": "NJ-1040",
          "line": "64",
          "description": "Child and dependent care credit"
        },
        {
          "form": "NJ-1040",
          "line": "65",
          "description": "New Jersey child tax credit (refundable)"
        }
      ],
      "couldApply": "unknown",
      "reason": "It needs a dependent and expenses the request does not carry.",
      "source": {
        "url": "https://www.nj.gov/treasury/taxation/pdf/current/1040i.pdf",
        "quote": "The Child and Dependent Care Credit is available to certain"
      }
    },
    {
      "id": "NJ-state-b9623e28",
      "category": "part-year",
      "description": "Married couples whose residency differs (engine 1.13.0): when one spouse is a full-year resident and the other a part-year resident, the joint return is not calculated: New Jersey requires the joint return, and no Division document says how the joint part-year NJ-1040 (one residency period) combines a full-year resident's income with a part-year spouse's or prorates the exemptions; when both spouses are part-year residents with different resident periods, the joint return is not calculated: New Jersey requires the joint return, and no Division document says how the joint part-year NJ-1040 (one residency period) handles two different residency periods.",
      "lines": [
        {
          "form": "PY/NR NJ-1040NR",
          "line": "couples-not-modelled",
          "description": "Married couples whose residency differs: the pairs and returns not calculated (each reason on the state page)"
        }
      ],
      "couldApply": false,
      "reason": "This is a full-year resident return (no part-year or nonresident residency given).",
      "source": {
        "url": "https://www.nj.gov/treasury/taxation/pdf/current/1040i.pdf",
        "quote": "If you are married and file a joint federal return, you must also file a joint New Jersey return. If you file separate federal returns, you must also file separate State returns."
      }
    }
  ],
  "stateDocs": "https://quantcalc.app/docs/state-tax/states/nj/",
  "engineVersion": "1.14.2"
}

More examples

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "VA",
  "filingStatus": "single",
  "age": 58,
  "wages": 30000,
  "pensionMilitary": 36000
}

Returns tax $910.90 (engine version 1.14.2); full response in the engine config download under api_examples.

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "CT",
  "filingStatus": "single",
  "age": 70,
  "iraDistributions": 40000,
  "socialSecurity": 25000,
  "socialSecurityGross": 30000
}

Returns tax $0 (engine version 1.14.2); full response in the engine config download under api_examples.

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "CA",
  "filingStatus": "single",
  "age": 67,
  "pensionPrivate": 48000,
  "iraDistributions": 12000,
  "socialSecurity": 20400,
  "socialSecurityGross": 24000,
  "projection": {
    "year": 2040,
    "inflation": 0.025
  }
}

Returns tax $691.21 (engine version 1.14.2); full response in the engine config download under api_examples.

POST https://quantcalc.app/api/state-tax
Content-Type: application/json
X-License-Key: YOUR_KEY

{
  "state": "CA",
  "filingStatus": "single",
  "age": 67,
  "pensionPrivate": 48000,
  "iraDistributions": 12000,
  "socialSecurity": 20400,
  "socialSecurityGross": 24000
}

Returns tax $1,415.08 (engine version 1.14.2); full response in the engine config download under api_examples.

Errors

Status	When
400	The request is refused before any tax is computed. The body is `{"error": "..."}` with one of the messages below; checks run in the order shown on the calculation order page and the first failure is returned.
403	No licence key, or a key without API access (including an expired one). The body carries `docs` and `contact`.
429	More than 120 requests a minute, or 30 in ten seconds, from one IP address (our edge limit).

Every 400 message, verbatim

Read from the engine's request handler. {1} and {2} stand for the parts filled in from the request.

Message	When
`Invalid JSON body`	The body is not JSON (or is empty).
`{1} must be a string, one of: single, mfj, married_filing_jointly, mfs, married_filing_separately, hoh, head_of_household, qss, qualifying_surviving_spouse`	filingStatus is present and not a string. {1} = filingStatus or filing_status, as sent.
`{1} "{2}" is not recognised — use one of: single, mfj, married_filing_jointly, mfs, married_filing_separately, hoh, head_of_household, qss, qualifying_surviving_spouse`	filingStatus is a string that is not one of the nine. {2} = the first 40 characters sent.
`{1} must be a number (annual dollars)`	An amount added in 1.1.0 (top level or in spouse) is not a number. {1} = its name, e.g. wages or spouse.pensionPublic. Since engine 1.5.0 this covers ordinaryIncome, socialSecurity and capitalGains too.
`pensionPublicSsCovered must be true or false (was the pensionPublic service covered by Social Security?)`	pensionPublicSsCovered is present, not null and not a boolean.
`{1} must be true or false ({2})`	blind, disabled, spouse.blind or spouse.disabled is present, not null and not a boolean. {1} = the field; {2} = what it asks.
`spouse must be an object`	spouse is present, not null and not an object.
`spouse.age must be a whole number between 1 and 120`	spouse.age is not a whole number from 1 to 120.
`state is required — a two-letter code such as "CA", or "DC"`	state (and state_code) absent, empty or not a string.
`state is not one we carry — expected a US state code or "DC"`	state is not a code the engine carries.
`income components cannot be negative`	ordinaryIncome, socialSecurity or capitalGains is negative.
`age must be a whole number between 0 and 120`	age is present, not null and not a number, or has a fraction (engine 1.5.0).
`age must be between 0 and 120`	age is a whole number outside 0 to 120.
`{1} must be a finite number`	Any amount other than ordinaryIncome, socialSecurity and capitalGains (top level or in spouse) is not finite. {1} = its name.
`{1} cannot be negative`	Any amount other than ordinaryIncome, socialSecurity and capitalGains (top level or in spouse) is negative. {1} = its name.
`{1} is larger than the engine accepts ($100 billion)`	Any amount other than ordinaryIncome, socialSecurity and capitalGains (top level or in spouse) exceeds $100,000,000,000. {1} = its name. The three household totals have no upper limit.
`socialSecurityGross must be at least socialSecurity (the federally-taxable part of the benefits)`	Both are given and gross is positive but below the taxable amount.
`out of memory`	The evaluation could not allocate memory (returned as 400).
`bad request`	Fallback when an evaluation fails without a message (not reached by the checks above).
`{1} must be one of: none, sepp, death, disability, other (the federal early-withdrawal exception for earlyDistributions)`	earlyDistributionException (top level or spouse) is not one of the five strings. {1} = the field.
`dependents must be an array of objects such as [{"age": 10}] (the people claimed as dependents; [] for none)`	dependents is present and not an array.
`dependents can list at most 20 people`	dependents has more elements than the engine carries.
`{1} must be an object such as {"age": 10}`	An element of dependents is not an object. {1} = dependents[i].
`{1}.{2} is not a dependent field — allowed: age, student, disabled`	A dependent carries another key. {1} = dependents[i], {2} = the key.
`{1}.age is required: a whole number between 0 and 120 (age at the end of the year)`	A dependent's age is missing, not a whole number or out of range. {1} = dependents[i].
`spouse.{1} is not a spouse field (the spouse's own amounts and facts only; ordinaryIncome, gains and socialSecurity are household totals at the top level)`	spouse carries a key that is not a spouse field. {1} = the key.
`on a married-filing-separately return spouse may carry only age and blind (the spouse's income is on their own return)`	spouse on an mfs return carries an amount or another fact.
`spouse is only valid with filingStatus "mfj" (married filing jointly), or with "mfs" for the spouse's age and blindness`	spouse is sent with single or head of household.
`spouse.earlyDistributions cannot exceed spouse.iraDistributions (it is the part of them taken before age 59½)`	The spouse's early part is larger than the spouse's IRA distributions (no spouse.employerPlanDistributions given).
`spouse.socialSecurityGross is the spouse's part of socialSecurityGross, so it needs socialSecurityGross (the household total) and cannot exceed it`	spouse.socialSecurityGross without the household figure, or larger than it.
`earlyDistributions cannot exceed iraDistributions (it is the part of them taken before age 59½)`	The early part is larger than the IRA distributions (no employerPlanDistributions given).
`spouse.earlyDistributions cannot exceed spouse.iraDistributions plus spouse.employerPlanDistributions (it is the part of them taken before age 59½)`	The spouse's early part is larger than the spouse's IRA and employer-plan distributions together (spouse.employerPlanDistributions given).
`earlyDistributions cannot exceed iraDistributions plus employerPlanDistributions (it is the part of them taken before age 59½)`	The early part is larger than the IRA and employer-plan distributions together (employerPlanDistributions given).
`railroadRetirementTier1 is the Tier 1 part of socialSecurityGross (Social Security and Tier 1 benefits received), so it needs socialSecurityGross and cannot exceed it`	railroadRetirementTier1 without socialSecurityGross, or larger than it.
`spouse.railroadRetirementTier1 is the spouse's part of railroadRetirementTier1 (the household total), so it needs it and cannot exceed it, nor the spouse's own socialSecurityGross`	spouse.railroadRetirementTier1 without railroadRetirementTier1, larger than it, larger than spouse.socialSecurityGross, or leaving the primary filer more Tier 1 than the primary's own gross benefits.
`localTaxRate applies only where the engine includes a county income tax (Indiana and Maryland)`	localTaxRate is given for any other state.
`localTaxRate must be a fraction between %.4f and %.4f (the lowest and highest {1} county rate, e.g. 0.0202 for 2.02%%)`	localTaxRate is not finite or is outside the state's range (the two figures are the state's lowest and highest rate). {1} = the state's name.
`federalTax (after the nonrefundable credits) cannot exceed federalTaxBeforeCredits`	Both are given and federalTax is more than federalTaxBeforeCredits.
`{1} must be a whole number between {2} and {3} ({4})`	planMinimumRetirementAge or deceasedSpouseAge (top level or spouse) is present and not a whole number from 1 to 120. {1} = the field as spouse.x or x; {2}, {3} = 1, 120; {4} = what the field means.
`{1}planMinimumRetirementAge is the minimum retirement age of the plan paying {2}disabilityIncome, so it needs {3}disabilityIncome`	planMinimumRetirementAge is given without disabilityIncome at the same level. {1}-{3} = "" or "spouse.".
`{1}deceasedSpouseAge is the age a surviving spouse's deceased spouse would have reached, so it needs {2}survivorBenefits: true`	deceasedSpouseAge is given without survivorBenefits: true at the same level. {1}, {2} = "" or "spouse.".
`computeFederal must be true or false (should the federal engine supply the federal inputs?)`	computeFederal is present and not a boolean.
`{1}selfEmploymentIncome needs computeFederal: true (the state's earned income is the net profit less half the self-employment tax, which only the federal return computes); without computeFederal, send the state earned income as wages`	selfEmploymentIncome (or spouse.selfEmploymentIncome) is not 0 and computeFederal is not true. {1} = empty for the filer, spouse. for the spouse.
`computeFederal: {1} is not modelled by the federal engine ({2}) yet: {3}. Leave computeFederal out and send federalTax, federalNiit, federalTaxBeforeCredits and federalRefundableCredits yourself.`	computeFederal: true with a field the federal engine does not model. {1} = the field, {2} = the federal engine version, {3} = what it would need.
`computeFederal needs age (the filer's age at the end of the year: the federal §72(t) additional tax, §63(f) aged amount and senior deduction read it)`	computeFederal: true without age.
`computeFederal with filingStatus mfj needs spouse.age (the spouse's §63(f) aged amount and senior deduction depend on it)`	computeFederal: true on a joint return without spouse.age.
`computeFederal computes federalTax, federalNiit, federalTaxBeforeCredits and federalRefundableCredits: leave them out, or leave computeFederal out`	computeFederal: true with any of the four federal figures.
`computeFederal computes socialSecurity (the federally taxable part) from socialSecurityGross: send the gross benefits as socialSecurityGross and leave socialSecurity out`	computeFederal: true with a socialSecurity amount other than zero.
`computeFederal: the spouse's iraDistributions or employerPlanDistributions are taxed at the spouse's own age for the §72(t) additional tax, and the spouses are on different sides of 59½; the federal engine ({1}) applies it at one age. Leave computeFederal out and send federalTax, federalNiit, federalTaxBeforeCredits and federalRefundableCredits yourself.`	computeFederal: true, the spouse has IRA or plan distributions, and one spouse is under 60 at the end of the year while the other is not. {1} = the federal engine version.
`capitalLoss is the year's net capital loss, so capitalGains and shortTermGains must be 0 with it (net the gains against the losses first)`	capitalLoss above 0 with capitalGains or shortTermGains above 0.
`capitalLossCarryover is the part of capitalLoss carried in from earlier years, so it cannot exceed capitalLoss`	capitalLossCarryover above capitalLoss (including without capitalLoss).
`strict: not a field of this API: {1} (check the spelling, or leave strict out to ignore unknown keys)`	strict is true and the request has top-level keys the API does not read. {1} = up to five of them, quoted, then " and N more".
`projection must be an object such as {"year": 2040, "inflation": 0.025} (the tax year to estimate and the inflation to assume)`	projection is present and not an object (null means absent).
`projection.{1} is not a projection field — allowed: year, inflation, cpiFactor, indexing`	projection carries another key. {1} = the key.
`projection.year is required: a whole number, the tax year to estimate ({1} to {2})`	projection has no year, or year is not a whole number. {1} = 2026, {2} = 2100.
`projection needs exactly one of inflation (the annual CPI assumption, e.g. 0.025) or cpiFactor (your own cumulative CPI factor from {1} to projection.year)`	projection has neither inflation nor cpiFactor, or both. {1} = 2026.
`projection.indexing must be "law" (the default: each state amount the way its law moves it) or "inflation" (every amount QuantCalc's planner scaled before engine 1.10.0 rises with inflation)`	projection.indexing is present, not null, and not "law" or "inflation" (any case).
`projection.year must be a whole number from {1} (the rules year) to {2}`	projection.year is before 2026 or after 2100. {1} = 2026, {2} = 2100.
`projection.inflation must be an annual rate between -0.10 and 0.25 (0.025 is 2.5 percent a year)`	projection.inflation is outside -0.10 to 0.25.
`projection.cpiFactor must be a number between 0.01 and 100 (the cumulative CPI factor from {1} to projection.year, e.g. 1.44)`	projection.cpiFactor is outside 0.01 to 100. {1} = 2026.
`projection.cpiFactor must be 1 when projection.year is {1} (the rules year itself)`	projection.year is 2026 and cpiFactor is not 1. {1} = 2026.
`projection refused: this result depends on {1}'s {2}, and how the law moves it after {3} is not established from an official source (leave projection out for {4})`	A projection past 2026 whose result depends on an amount the indexing registry marks not established. {1} = the state, {2} = the engine field, {3} and {4} = 2026 (indexing "law" only).
`localities must be an array of jurisdiction codes such as ["NY-NYC"] (GET /api/state-tax/localities?state=XX lists them)`	localities is present and not an array.
`localities can list at most {1} jurisdictions`	More than 6 entries.
`localities[{1}].role must be "resident" (the household lives there) or "work" (a workplace)`	role is not resident or work.
`localities[{1}].wages must be a number (the wages earned there)`	wages is not a number.
localities[{1}] must be a jurisdiction code such as "NY-NYC", or an object with one in `code`	An entry is neither a code string nor an object with one.
`localities[{1}]: "{2}" is not a jurisdiction code the engine knows (GET /api/state-tax/localities?state={3} lists them)`	The code is not in the registry.
`localities[{1}]: {2} is in {3}, and this request is for {4}`	A code of another state.
`localities[{1}]: {2} taxes on a base the engine does not model (a grandfathered ordinance that reaches intangible income)`	Wyoming or Indian Hill (Ohio).
`localities[{1}]: {2} taxes residents only (role "work" applies to the earned-income taxes of a workplace)`	A workplace for a tax on residents only.
`localities[{1}].wages applies to a workplace (role "work") only: a residence's tax reaches the household's whole income`	wages on a residence.
`localities[{1}]: {2} is a second residence of the same kind (one county, school district, municipality or city per return)`	Two residences in one slot.
`localities: the wages earned at workplaces exceed the household's wages`	The workplaces' wages add up to more than the household's.
`localTaxRate and a county in localities say the same thing: give one`	Both given.
`otherLocalTaxCredit is a resident's credit against a local return: it needs a residence in localities that files one`	No residence with a separate local return.
`localUnearnedIncome is the base of Philadelphia's School Income Tax: it needs localities ["PA-PSD-510101"]`	No Philadelphia residence.
`{1} needs localities (the jurisdictions it is about)`	otherLocalTaxCredit or localUnearnedIncome without localities.
`rentIncludesHeat describes rentPaid: give the rent too`	rentIncludesHeat without a positive rentPaid.
`residency must be an object: {"status": "partYear" or "nonresident", "residentFrom", "residentTo", "stateIncome": {...}}`	residency is present and not an object.
`residency.status is required: "resident", "partYear" or "nonresident"`	residency.status is absent or another value.
`a part-year or nonresident return is not modelled with {1}; leave them out or drop residency`	An input the residency rules do not take. {1} = the inputs.
`Washington's capital gains excise for a part-year resident or nonresident is not modelled`	WA with residency and capital gains.
`residency.stateIncome.{1} is more than the year's {2}: the state's part is a part of the whole`	A stateIncome amount above the year's amount of the same key. {1}, {2} = the key.
`a nonresident's retirement income is not taxable by the state: "No State may impose an income tax on any retirement income of an individual who is not a resident or domiciliary of such State" (4 U.S.C. 114(a)); stateIncome retirement amounts must be 0`	A nonresident's stateIncome with IRA, pension or conversion amounts.
`Social Security received while a nonresident is not income from the state's sources; stateIncome.socialSecurity and socialSecurityGross must be 0 on a nonresident return`	A nonresident's stateIncome with Social Security.
`{1}'s part-year / nonresident instructions do not say how to apportion when the whole-year income is zero or less and the {2} income is not; not computed`	The whole-year income measure is zero or less, the state's is not, there is tax to apportion, and the state's instructions are silent. {1}, {2} = the state.
`{1}{2} must be a date of {3} written YYYY-MM-DD`	A date of residency or residency.spouse is not a date of the tax year. {1} = residency. or residency.spouse., {2} = the key, {3} = the tax year.
`{1}stateIncome must be an object of amounts (the income the state taxes)`	residency.stateIncome or residency.spouse.stateIncome is not an object. {1} = the prefix.
`{1}stateIncome.{2} is not an amount the residency rules take — allowed: wages, ordinaryIncome, shortTermGains, capitalGains, capitalLoss, iraDistributions, pensionPrivate, pensionPublic, rothConversion, socialSecurity, socialSecurityGross`	A stateIncome object has another key. {1} = the prefix, {2} = the key.
`residency.{1} is not a residency field — allowed: status, residentFrom, residentTo, stateIncome, spouse, spouseShare, election`	residency has another key. {1} = the key.
`residency.spouse must be an object: the spouse's own {"status", "residentFrom", "residentTo", "stateIncome"}`	Engine 1.13.0: residency.spouse is present and not an object.
`residency.spouse.{1} is not a residency field — allowed: status, residentFrom, residentTo, stateIncome`	residency.spouse has another key. {1} = the key.
`residency.spouse.status is required: "resident", "partYear" or "nonresident"`	residency.spouse.status is absent or another value.
`residency.spouseShare must be an object of amounts (the spouse's part of the household amounts)`	residency.spouseShare is present and not an object.
`residency.spouseShare.{1} is not a household amount — allowed: ordinaryIncome, shortTermGains, capitalGains, capitalLoss, capitalLossCarryover, socialSecurity`	residency.spouseShare has another key. {1} = the key.
`residency.election must be "joint", "separate" or "jointAsResidents"`	residency.election is another value or not a string.
`localities[{1}] needs both residentFrom and residentTo (the period lived there)`	Engine 1.13.0: a localities object has one of the two dates.
`localities[{1}].residentIncome must be an object of amounts (the income received while living there)`	localities[].residentIncome is not an object.
`localities[{1}].residentIncome.{2} is not an amount the local rules take — allowed: the keys of residency.stateIncome`	localities[].residentIncome has another key.
`{1}residentFrom, residentTo and stateIncome apply to a part-year or nonresident return; a full-year resident gives only status`	status resident with dates or stateIncome (residency or, engine 1.13.0, residency.spouse). {1} = the prefix.
`a part-year return needs {1}residentFrom and {2}residentTo (the resident period, YYYY-MM-DD)`	status partYear without both dates. {1}, {2} = the prefix.
`{1}residentFrom / residentTo apply to a part-year return only`	status nonresident with dates. {1} = the prefix.
`{1}residentFrom is after residentTo`	The resident period ends before it starts. {1} = the prefix.
`residency.spouse is for a married couple filing jointly: it needs filingStatus "mfj" and the spouse object (each spouse's own amounts)`	Engine 1.13.0: residency.spouse on a request that is not mfj, or without the spouse object.
`residency.spouseShare.{1} is more than the household's {2}`	A spouse's part exceeds the household amount. {1}, {2} = the key.
`residency.spouseShare.{1} is needed: the spouses' residency differs, so the state taxes each spouse's own part of the household's {2} (give the spouse's part; 0 = all the primary's)`	Engine 1.13.0: a household amount is not 0 and the couple's request does not split it.
`spouse.socialSecurityGross is needed: the spouses' residency differs, so each spouse's own benefits count (give the spouse's part of socialSecurityGross)`	Engine 1.13.0: socialSecurityGross is not 0 and the spouse object does not give the spouse's part.
`{1}{2} is more than the {3} own {4}: the state's part is a part of the whole`	Engine 1.13.0: a spouse's stateIncome amount exceeds that spouse's own amount. {1} = the prefix, {2}, {4} = the key, {3} = primary's or spouse's.
`a nonresident's retirement income is not taxable by the state: "No State may impose an income tax on any retirement income of an individual who is not a resident or domiciliary of such State" (4 U.S.C. 114(a)); {1} retirement amounts must be 0`	Engine 1.13.0: a nonresident spouse's stateIncome has retirement amounts. {1} = the prefix.
`Social Security received while a nonresident is not income from the state's sources; {1}socialSecurity and socialSecurityGross must be 0 on a nonresident's part`	Engine 1.13.0: a nonresident spouse's stateIncome has Social Security. {1} = the prefix.
`{1}'s instructions do not say how a married couple files when {2}; not computed (drop residency.spouse to compute each return yourself)`	Engine 1.13.0: the state's instructions do not address the couple's pair (the sourced list on the state's page). {1} = the state, {2} = the pair.
`residency.election "{1}" is not open to this couple in {2}: {3}`	Engine 1.13.0: the state does not allow the elected treatment for the pair. {1} = the election, {2} = the state, {3} = its rule.
`localities[{1}]: residentFrom, residentTo and residentIncome describe a residence (role "resident"), not a workplace`	Engine 1.13.0: a workplace with a period or residentIncome.
`localities[{1}]: a part-year Yonkers resident's nonresident earnings tax prorates the exclusion by the months of residence (Form Y-203), a table the engine does not carry: not modelled`	Engine 1.13.0: a Yonkers workplace beside a part-year Yonkers residence.
`localities[{1}].residentFrom is after residentTo`	Engine 1.13.0: a locality's period ends before it starts.
`localities[{1}]: {2} follows the {3} of residence on {4}: give that one, without residentFrom / residentTo`	Engine 1.13.0: a county or Iowa school district with a period. {2} = the locality, {3} = county or school district, {4} = the day.
`localities[{1}]: {2}`	Engine 1.13.0: a county or Iowa school district on a nonresident return (Maryland's special nonresident tax; Indiana's county of principal work, Schedule CT-40PNR Section 2; no Iowa school district). {2} = the reason.
`localities[{1}]: {2}: {3}`	Engine 1.13.0: on a part-year return, an Indiana county without January 1 residence, or an Iowa school district with the resident period ending before December 31. {2} = the locality, {3} = the reason.
`localities[{1}]: a nonresident of the state does not live in {2} (a workplace is role "work"{3})`	Engine 1.13.0: a resident locality on a nonresident return. {2} = the locality, {3} = NYC's note.
`localities[{1}]: the period lived in {2} must lie inside the state resident period`	Engine 1.13.0: a locality's period outside a part-year return's resident period.
`localities[{1}].residentIncome applies to a part-year resident of {2} (a full-year resident's base is the whole year's income)`	Engine 1.13.0: residentIncome for a locality lived in all year.
`localities[{1}]: a part-year resident of {2} is not modelled: {3}`	Engine 1.13.0: a part-year resident of a locality whose part-year rule is not settled (engine 1.14.0: Michigan cities, Louisville Metro, Wilmington; Philadelphia's and Kansas City / St. Louis's with net profits; Kansas City / St. Louis on a joint request with both spouses' wages). {3} = the reason.
`localities[{1}].residentIncome is needed: a part-year resident of {2} is taxed on the income received while living there`	Engine 1.13.0: a part-year resident of NYC, Yonkers or an Ohio school district without residentIncome.
`localities[{1}].residentIncome.{2} is more than the year's {3}`	Engine 1.13.0: a residentIncome amount exceeds the year's.
`residency.spouseShare and residency.election are about a married couple whose residency differs: they need residency.spouse (the spouse's own residency)`	Engine 1.13.0: spouseShare or election without residency.spouse.
`rentalNetIncome must be a finite number between -$100 billion and $100 billion`	rentalNetIncome not finite, or beyond the limit either way.
`rentalNetIncome is not supported with residency (a part-year or nonresident return): the state-source part of a rental is not modelled; send it as stateIncome.ordinaryIncome (income only)`	rentalNetIncome not 0 with residency.
`localities[{1}]: rentalNetIncome is not supported for a part-year resident of {2} (the resident period's share of a rental is not modelled)`	rentalNetIncome not 0 with a locality lived in for part of the year. {1} = the index, {2} = the locality's name.
`localities[{1}].{2} is not a locality field — allowed: code, role, wages, residentFrom, residentTo, residentIncome, daysOutside, workDays`	A localities object has another key. {1} = the index, {2} = the key.
`{1}: {2}; not computed{3}`	Engine 1.13.0: the treatment that applies to the couple is one the engine does not compute. {1} = the state's rule, {2} = why, {3} (engine 1.14.0) = the election that computes another option the couple may take, when one was computed.
`localities[{1}].daysOutside and workDays apply to a part-year resident of Kansas City or St. Louis (their non-residency deduction formula), with residentFrom / residentTo`	Engine 1.14.0: the formula days on another locality, a workplace, or a full-year residence.
`localities[{1}].daysOutside is needed: a part-year resident of {2} deducts the wages x the days {3} / the work days`	Engine 1.14.0: a part-year Kansas City or St. Louis resident without daysOutside. {3} = the city's own day rule.
`localities[{1}].workDays does not apply to Kansas City: Form RD-109NR line 1 says "Enter 260 for days worked everywhere."`	Engine 1.14.0: workDays on a Kansas City residence.
`localities[{1}].daysOutside ({2}) is more than the work days ({3})`	Engine 1.14.0: the deducted days exceed the work days.
`localities[{1}].residentIncome does not apply to {2}: {3}`	Engine 1.13.0: residentIncome for a locality whose part-year rule takes the period instead (a PA EIT subdivision's months; engine 1.14.0: an Ohio traditional-base district's residency factor, Kansas City / St. Louis's day formula). {3} = the rule.
`localities[{1}].daysOutside and workDays apply to a part-year resident of {2} (a full-year resident's wages are all taxed)`	Engine 1.14.0: the formula days on a whole-year residence. {2} = the city.

A refusal always carries a reason, rather than a confident zero. For example, "filingStatus": "joint" returns:

HTTP 400
{
  "error": "filingStatus \"joint\" is not recognised — use one of: single, mfj, married_filing_jointly, mfs, married_filing_separately, hoh, head_of_household, qss, qualifying_surviving_spouse"
}

Metadata endpoints

Three read-only endpoints describe the engine. They need no key: everything they return is already published on these pages and in the JSON downloads, and open they let you validate requests and read the rules before you have a key.

Endpoint	Returns
`GET /api/state-tax/states`	The 51 jurisdictions: code, name, whether it taxes income, the verification tier with its meaning and whether the whole return is replayed line by line in the tests, the number of source citations, the rule families with no official source, the state page and its `/rules` URL.
`GET /api/state-tax/rules?state=NJ`	One jurisdiction's full rule set as the engine applies it, from the same data as its state page: `config` (every parameter; the engine config download says what each one is), `brackets` per filing status, `statusParams` (what each status gets), `ruleProbes` (phase-out tables and similar), `families` (per rule family: its page anchor, every source with all its verified claims and the engine value each supports, the review notes, and the reason if it has no official source), `sourceDifferences`, `notes`, the `verification` record and `indexing` (how each amount moves after 2026, rule by rule with its sources, and the changes enacted for later years that a projection does not apply: the registry). The code is case-insensitive; a missing or unknown one is a 400.
`GET /api/state-tax/schema`	A JSON Schema (draft 2020-12) generated from the request parser's own field table: `$defs.request` (every key and its snake_case spelling, types, limits, what an absent key means, and every 400 message under `x-errors`), `$defs.response` and `$defs.error`. Also a download.

Validating a request before sending it, in Python:

import json, urllib.request, jsonschema
schema = json.load(urllib.request.urlopen("https://quantcalc.app/api/state-tax/schema"))
request = {"state": "NJ", "filingStatus": "mfj", "age": 67, "pensionPublic": 40000}
jsonschema.validate(request, {**schema, "$ref": "#/$defs/request"})

The schema cannot express the checks that relate two fields (for example, earlyDistributions at most iraDistributions plus employerPlanDistributions); the API refuses those with the messages listed under x-errors. Every request in the library's parity corpus that the API accepts validates against it (checked on every build).

What GET /api/state-tax/states returns (three of the 51 entries):

{
  "engineVersion": "1.14.2",
  "taxYear": 2026,
  "count": 51,
  "states": [
    {
      "code": "ID",
      "name": "Idaho",
      "taxesIncome": true,
      "verification": {
        "tier": "a",
        "meaning": "Worksheet-tested: at least one golden scenario or unit test pins an exact dollar result for this state, hand-computed independently of the engine, and the test's own derivation names the state form, worksheet or rate schedule it follows.",
        "lineByLineReplay": true
      },
      "sources": 32,
      "unsourcedFamilies": [
        "social_security",
        "retirement_income",
        "roth_conversion"
      ],
      "docs": "https://quantcalc.app/docs/state-tax/states/id/",
      "rules": "https://quantcalc.app/api/state-tax/rules?state=ID"
    },
    {
      "code": "NJ",
      "name": "New Jersey",
      "taxesIncome": true,
      "verification": {
        "tier": "a",
        "meaning": "Worksheet-tested: at least one golden scenario or unit test pins an exact dollar result for this state, hand-computed independently of the engine, and the test's own derivation names the state form, worksheet or rate schedule it follows.",
        "lineByLineReplay": false
      },
      "sources": 20,
      "unsourcedFamilies": [],
      "docs": "https://quantcalc.app/docs/state-tax/states/nj/",
      "rules": "https://quantcalc.app/api/state-tax/rules?state=NJ"
    },
    {
      "code": "TX",
      "name": "Texas",
      "taxesIncome": false,
      "verification": {
        "tier": "none",
        "meaning": "No broad personal income tax: nothing to compute beyond any special levy the page lists.",
        "lineByLineReplay": false
      },
      "sources": 2,
      "unsourcedFamilies": [],
      "docs": "https://quantcalc.app/docs/state-tax/states/tx/",
      "rules": "https://quantcalc.app/api/state-tax/rules?state=TX"
    }
  ]
}

Access

POST /api/state-tax is licensed: send the key as X-License-Key. The three metadata endpoints are public.

curl -s https://quantcalc.app/api/state-tax \
  -H 'content-type: application/json' \
  -H 'X-License-Key: YOUR_KEY' \
  -d '{"state":"CT","filingStatus":"single","age":70,"iraDistributions":40000,"socialSecurity":25000,"socialSecurityGross":30000}'

Evaluation

An evaluation key lets you cross-check the engine against your own model before you license it.

Time-limited. It is an ordinary licence key whose expiry date is part of the key itself (normally 30 days out). The API checks it on every call and answers 403 once the date has passed; we can also revoke it earlier.
Licensed endpoints. It opens POST /api/state-tax. The metadata endpoints need no key at all.
Test households only. Use made-up or fully anonymised households. We do not store request bodies, except that a request failing with a server error is kept for 2 days (body and IP address included) to diagnose it. Either way, an evaluation is not the place for a client's data.
Limits. 120 requests a minute (30 in any ten seconds) per IP address, at our edge.

Ask for one at [email protected]. Then:

# 1. what we cover, and how each state is verified (no key)
curl -s https://quantcalc.app/api/state-tax/states

# 2. one state's rules and sources, as the engine applies them (no key)
curl -s 'https://quantcalc.app/api/state-tax/rules?state=NJ'

# 3. the request schema, to validate your households first (no key)
curl -s https://quantcalc.app/api/state-tax/schema -o state-tax-api-schema.json

# 4. a household: the tax, the rules and exclusions that produced it, and their sources
curl -s https://quantcalc.app/api/state-tax \
  -H 'content-type: application/json' \
  -H "X-License-Key: $QC_KEY" \
  -d '{"state":"GA","filingStatus":"mfj","age":67,"iraDistributions":30000,"pensionPublic":22000,"ordinaryIncome":4000,"qualifiedDividends":6000,"capitalGains":12000,"socialSecurity":27200,"socialSecurityGross":32000,"spouse":{"age":63,"wages":48000,"employerPlanDistributions":15000}}'

To compare with your model, read breakdown (the taxable income and what entered it) and perPerson (each person's exclusions and the rule that gave them) before tax: a difference usually shows up there first, and rules.sources points at the page and the quote to check it against.

Integration models

Three ways to use the engine, depending on where your calculation has to run:

Model	What you get	Fits when
Metered API	This endpoint. Rules and data are updated on our side; the response carries `engineVersion` and `taxYear`.	Your application can make a network call per calculation.
Library build	The engine compiled into your application: the same C code, with a JSON-in/JSON-out entry point built on the same parser and response builder as this API (sources included), and a typed interface. See library and delivery.	The calculation must run inside your application, offline, or at volume.
Rules and tables	The engine configuration and provenance as data, for teams that implement the arithmetic themselves.	You have your own tax engine and want the state data and its sources.

Whichever model you use, the per-state pages under States are the specification, and the verification page says how far each state has been tested.

What the endpoint does not include

Federal income tax and FICA (computeFederal runs the federal engine for the federal amounts the state return reads).
Local income taxes outside the locality registry: localities takes the jurisdictions GET /api/state-tax/localities lists; without them, Indiana and Maryland carry their county tax at the state's population-weighted average rate unless localTaxRate gives the filer's own.
Itemized deductions and credits beyond those each state page lists.
The part-year, nonresident and couple cases each state page lists as not calculated. Part-year and nonresident returns are calculated by each state's own method (residency, engine 1.12.0); a married couple whose residency differs by the state's own rule for the pair, every treatment it allows computed and reported in residency.couple (residency.spouse, engine 1.13.0); and a part-year resident's local taxes where the locality's rule is settled (localities[].residentFrom, engine 1.13.0).
A tax year after 2026 is an estimate (projection): rates, rules and enacted future changes other than dollar amounts are the 2026 ones.

The summary dataset behind the site's comparison tables is published separately under CC-BY-4.0 at /data/state-retirement-tax/2026/. It is not enough to compute a liability; the endpoint is. QuantCalc is calculation software, not tax advice.