Compute a state return
Computes a California Form 540, a New York IT-201 (with NYC resident tax), an Illinois IL-1040, a North Carolina D-400 or a Michigan MI-1040, chosen by state; the federal return is computed underneath, so federal facts such as medicareWages apply. For AK, FL, NV, SD, TX, WY, TN, NH and WA it answers $0 state income tax or declines, and the CA/NY/IL/NC/MI field rules do not apply.
Compute a state return (CA, NY, IL, NC, MI, or a no-income-tax state; discriminated by `state`).
Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer <API key> |
| Content-Type | Yes | application/json |
| Idempotency-Key | No (recommended) | Optional. A unique key per logical request (one key per operation). Retrying with the SAME key + SAME request body replays the byte-identical first response (with header `Idempotent-Replayed: true`)…Optional. A unique key per logical request (one key per operation). Retrying with the SAME key + SAME request body replays the byte-identical first response (with header `Idempotent-Replayed: true`) and bills exactly ONCE. The SAME key with a DIFFERENT body → 409 `idempotency_key_reused`. A concurrent in-flight duplicate → 409 `idempotency_key_in_progress` (retry). Keys are scoped per account and replay for 24h. Errors (4xx/5xx) are NOT cached — a retry after an error is a fresh request. |
Request body: California
"state": "ca". 84 fields.
| Field | Description |
|---|---|
| yearintegerrequired | Tax year; a year the state engine does not model declines. |
| filingStatus"single" | "married_filing_jointly" | "married_filing_separately" | "head_of_household"required | REQUIRED. The state endpoint re-runs the FEDERAL pipeline to derive its starting point, so it needs the same filing status the federal endpoint does. |
| wagesnumber | Same as FederalProfile.wages. |
| medicareWagesnumber | Medicare wages (W-2 box 5). CONDITIONALLY REQUIRED, and the condition cannot be expressed in this schema's `required` array, which is why it is spelled out here. This endpoint re-runs the FEDERAL…Medicare wages (W-2 box 5). CONDITIONALLY REQUIRED, and the condition cannot be expressed in this schema's `required` array, which is why it is spelled out here. This endpoint re-runs the FEDERAL pipeline, and that pipeline declines its Additional Medicare Tax determination whenever box 5 is omitted AND at least one of the federal pipeline's W-2 evidence fields is POSITIVE (the trigger is a positive amount, not mere presence: an explicit 0 does not arm it). Those fields are `wages`, `federalWithholding`, `medicareTaxWithheld` and `socialSecurityWages`, and this endpoint accepts all four, so a positive value in any of them arms it. WHAT A STATE CALLER ACTUALLY RECEIVES: `computed:false` with code `federal_declined` - NOT the federal-side code `surtax_additional_medicare`, which this endpoint does not surface; the box-5 explanation arrives in `reason`. Rationale: box 5 can exceed box 1 by an unbounded amount for real filers - 401(k)/403(b)/457(b) elective deferrals reduce box 1 while remaining subject to Medicare tax - so no finite margin can rule out the Additional Medicare Tax threshold being crossed at box 5. It is NOT required in the absence of positive W-2 evidence: a dividends-only or zero-wage return computes without it. Declared because a caller building exactly what this schema prescribes must be able to learn this requirement from the schema itself. |
| federalWithholdingnumber | Same as FederalProfile.federalWithholding. |
| medicareTaxWithheldnumber | Same as FederalProfile.medicareTaxWithheld. |
| taxableInterestnumber | CA/NY: requires stateIncomeConformsToFederal:true (else non-wage income declines); IL, NC and MI take it without. |
| ordinaryDividendsnumber | CA/NY: requires stateIncomeConformsToFederal:true. |
| qualifiedDividendsnumber | ≤ ordinaryDividends; CA/NY/IL/NC/MI tax it as ordinary (no preferential rate); CA/NY require stateIncomeConformsToFederal:true. |
| reit199ADividendsnumber | Same as FederalProfile.reit199ADividends. |
| netShortTermCapGainnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Taxed as ordinary by CA/NY/IL/NC/MI; CA/NY require stateIncomeConformsToFederal:true. |
| netLongTermCapGainnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Taxed as ordinary by CA/NY/IL/NC/MI; CA/NY require stateIncomeConformsToFederal:true. |
| priorYearCapLossCarryoverSTnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year SHORT-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Applied with the §1211(b) −$3,000 (−$1,500 MFS) annual limit. THIS ENDPOINT DOES NOT RETURN AN ENDING CARRYOVER: endingCapLossCarryoverST is a FEDERAL-response field and the state response has no equivalent, so track the remaining carryover yourself or read it from /federal. This field is the PRIOR-YEAR carryover only — do NOT also net it into netShortTermCapGain/netLongTermCapGain, which are CURRENT-YEAR nets before any carryover; doing both applies it twice (an executed $12,120 under-tax). Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. Accepted on the STATE endpoint for the same reason: this endpoint re-runs the federal pipeline, so this field's presence arms the identical Schedule-D-presence affirmation gates described above, and a caller who omits a zero-net carryover here bypasses them exactly as on /federal. If only an AMT-side carryover exists, send 0 (the return declines). |
| priorYearCapLossCarryoverLTnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year LONG-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Nets against long-term gain. THIS ENDPOINT DOES NOT RETURN AN ENDING CARRYOVER: endingCapLossCarryoverLT is a FEDERAL-response field and the state response has no equivalent, so track the remaining carryover yourself or read it from /federal. Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. Accepted on the STATE endpoint for the same reason: this endpoint re-runs the federal pipeline, so this field's presence arms the identical Schedule-D-presence affirmation gates described above, and a caller who omits a zero-net carryover here bypasses them exactly as on /federal. If only an AMT-side carryover exists, send 0 (the return declines). |
| capLossCarryoverNoAmtDifferenceAffirmedtrue | §6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the trigger is PRESENCE, not magnitude, and not the carryover field specifically.§6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the trigger is PRESENCE, not magnitude, and not the carryover field specifically. WHAT `true` ATTESTS (identical to FederalProfile.capLossCarryoverNoAmtDifferenceAffirmed): EITHER (a) this return has no prior-year capital-loss carryover at all, for regular tax or AMT — the common case, and attesting true is how you say so — OR (b) a carryover exists and its ENTERING AMT-SIDE amount equals its regular-tax amount. It covers a carryover HOWEVER it reached this engine, including one the caller already netted into netShortTermCapGain/netLongTermCapGain, and it additionally attests the carryover was NOT supplied BOTH ways (netted into a scalar AND as priorYearCapLossCarryover*), which would apply it twice. DO NOT SUPPLY IT DEFENSIVELY: on a return carrying NO Schedule D input at all this is a contradictory orphan affirmation and the return is DECLINED - a state caller receives `computed:false` with code `federal_declined`, the orphan explanation in `reason`. An AMT-only carryover is NOT covered: send priorYearCapLossCarryoverST/LT as 0, and the return declines. |
| mortgageInterestnumber | Same as FederalProfile.mortgageInterest. |
| mortgageAvgBalancenumber | Same as FederalProfile.mortgageAvgBalance. |
| mortgageInterestExcludesExcessRefinancingProceedsboolean | Same as FederalProfile.mortgageInterestExcludesExcessRefinancingProceeds. |
| mortgageInterestSecuresAmtQualifiedDwellingboolean | Same as FederalProfile.mortgageInterestSecuresAmtQualifiedDwelling. |
| mortgageInterestSecuresSec121PrincipalResidenceboolean | Same as FederalProfile.mortgageInterestSecuresSec121PrincipalResidence. |
| foreignTaxPaidnumber | Same as FederalProfile.foreignTaxPaid. |
| foreignIncomeAllPassive1099true | Same as FederalProfile.foreignIncomeAllPassive1099: all foreign income is passive and shown on a qualified payee statement (§6724(d)(2)), which is broader than the 1099 family. |
| foreignTaxIsFullyCreditableAffirmedtrue | Same as FederalProfile.foreignTaxIsFullyCreditableAffirmed. |
| foreignSourceGrossIncomenumber | Same as FederalProfile.foreignSourceGrossIncome. |
| foreignQualifiedDividendsAndCapGainsnumber | Same as FederalProfile.foreignQualifiedDividendsAndCapGains. |
| foreignTaxNoCarryoverAffirmedtrue | Same as FederalProfile.foreignTaxNoCarryoverAffirmed. |
| foreignSourceNoForm1116PartILines2Through5EntryAffirmedtrue | Same as FederalProfile.foreignSourceNoForm1116PartILines2Through5EntryAffirmed. |
| foreignSourceNoForm1116Line16AdjustmentAffirmedtrue | Same as FederalProfile.foreignSourceNoForm1116Line16AdjustmentAffirmed. |
| foreignTaxNoForm1116Line12ReductionAffirmedtrue | Same as FederalProfile.foreignTaxNoForm1116Line12ReductionAffirmed. |
| stateLocalIncomeTaxnumber | Same as FederalProfile.stateLocalIncomeTax. |
| realEstateTaxnumber | Same as FederalProfile.realEstateTax. |
| sec1250UnrecapturedGainnumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.sec1250UnrecapturedGain. |
| collectibles28Gainnumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.collectibles28Gain. |
| specialRateGainNoAmtScheduleDDifferenceAffirmedboolean | Same as FederalProfile.specialRateGainNoAmtScheduleDDifferenceAffirmed. |
| collectibles28NoSec1202ExclusionPreferenceAffirmedtrue | §6694 affirmation REQUIRED on the same Schedule-D-presence trigger.§6694 affirmation REQUIRED on the same Schedule-D-presence trigger. WHAT `true` ATTESTS (identical to FederalProfile.collectibles28NoSec1202ExclusionPreferenceAffirmed): EITHER no §1202 qualified-small-business-stock exclusion is involved on this return at all, OR every §1202 exclusion claimed arises solely from stock acquired AFTER 2010-09-27 and so carries no §57(a)(7) AMT preference. This engine hardcodes AMT other-preferences to $0, so an unattested pre-2010-09-28 exclusion would UNDER-state AMT — and the preference is 7% of the EXCLUDED gain, which no input here carries and which netting cannot reduce, so it survives even when every capital-gain figure on the return nets to $0. That is why the trigger is presence of Schedule D activity rather than a positive amount. DO NOT SUPPLY IT DEFENSIVELY: on a return carrying NO Schedule D input at all this is a contradictory orphan affirmation and the return is DECLINED - a state caller receives `computed:false` with code `federal_declined`, the orphan explanation in `reason`. |
| qbiDeductionnumber | Same as FederalProfile.qbiDeduction; on /state the decline arrives as federal_declined. |
| pensionDistributionTaxablenumber | State (CA, NY, IL, NC, MI) — the fully-taxable federal line-4b/5b pension/IRA distribution (with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true).State (CA, NY, IL, NC, MI) — the fully-taxable federal line-4b/5b pension/IRA distribution (with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true). IL subtracts it with ilPensionIsQualifiedRetirementIncomeAffirmed; NC taxes it (its retirement deductions are not modeled, an over-tax); MI: see miNoRetirementOrAgeDeductionsAffirmed and miRetirementFactsAffirmed. NY EXCLUDES it: supply nyPensionIsGovernmentPension (IT-201 line 26, full) OR nyPrivatePensionQualifiesFor20kExclusion (IT-201 line 29, min($20k,5b)); neither → the pension stays NY-taxable. CA CONFORMS and TAXES it by default, with ONE modeled exclusion: caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true excludes min($20,000, line 5b), AGI-gated (R&TC §§17132.9/17132.10) — and a VERIFY flag names the unmodeled CA divergences enumerated in CA_COMPUTE_CAPABILITY.state_adjustments.pension (served on GET /api/mcp/tax-compute/state), which is the single authoritative list — this text states no count of its own, because a count restated in many places is a claim that must be maintained in many places, and on this surface it was not. (1) Tier-2 railroad retirement (RRB-1099-R), which CA EXCLUDES (45 U.S.C. §231m) — omitting it OVER-taxes. (2) CA's early-distribution additional tax, which this engine computes for NEITHER jurisdiction: 2.5% (R&TC §17085(c)(1)), raised to 6% where §72(t)(6) applies (§17085(c)(2), FTB 3805P line 4), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax — omitting THIS one UNDER-taxes. (3) An IRA-to-HSA one-time funding distribution under §408(d)(9), EXCLUDED from federal gross income under §408(d)(9)(A) but which California conforms out entirely (R&TC §17215.4) — the FTB 3805P instructions require it ADDED BACK to CA AGI, and — where the distribution is premature under the §72(t) rules — a 2 1/2% additional tax, which can be owed even where no federal §72(t) tax is. This one runs the OPPOSITE way from (1): omitting it UNDER-taxes California, and the engine has no field for it, so a CA return carrying one is outside the modeled surface. |
| pensionDistributionFullyTaxableAffirmedtrue | §6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint, one of TWO required affirmations):§6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint, one of TWO required affirmations): the fully-taxable 1099-R box 2a distribution, no basis/QCD/rollover/Roth/NUA. |
| pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmedtrue | §6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed (same contract as the federal endpoint).§6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed (same contract as the federal endpoint). THIS SCHEMA DELIBERATELY DOES NOT RESTATE THE RULE — see the federal endpoint's field of this name for the operative condition, which GOVERNS. (fed-pension-5b-72q-levy-exception-fix, 2026-08-29 — see the federal endpoint's pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmed field, required on the SAME contract here whenever this field is true and pensionDistributionIsNonqualifiedAnnuityNii is not explicitly false; and pensionDistributionNoSeppModificationRecaptureAffirmed, required on the SAME contract here whenever this field is true — regardless of which specific basis — per fed-pension-5b-sepp-modification-recapture-gate, 2026-08-29). SIMPLE-IRA timing within the §72(t)(6)(A) 2-year period does not by itself disqualify a 59½+ or exception-covered distribution — it only affects the RATE of a genuinely early, no-exception distribution, which this engine does not compute. CALIFORNIA DIVERGES on that rate and this engine computes it for neither jurisdiction: CA's analogue is 2.5% (R&TC §17085(c)(1)), 6% where §72(t)(6) applies (§17085(c)(2)), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax. THE 2-YEAR CLOCK IS ANCHORED TO PARTICIPATION IN THE EMPLOYER'S PLAN, NOT THE ACCOUNT'S AGE: §72(t)(6)(A) runs the period from 'the date such individual first participated in any qualified salary reduction arrangement maintained by the individual's employer under section 408(p)(2)', and IRS Notice 98-4 Q&A I-5 gives the operational start — 'the first day on which contributions made by the individual's employer are deposited in the individual's SIMPLE IRA' (the Form 5329 instructions and FTB 3805P agree). It is measured PER EMPLOYER, so a new employer's SIMPLE starts a NEW 2-year period for that employer's own contributions — reading the clock as the ACCOUNT's age can UNDER-tax at 10%/2.5%. A transfer or rollover between SIMPLE IRAs under the SAME employer's arrangement does not restart it. ACROSS EMPLOYERS THE PERIOD FOLLOWS EACH EMPLOYER'S OWN CONTRIBUTIONS — 26 CFR §1.408A-4 A-4(b): 'This 2-year period of section 408(d)(3)(G) applies separately to the contributions of each of an individual's employers maintaining a SIMPLE IRA Plan' — and A-4(b) itself identifies that period as 'the 2-year period described in section 72(t)(6)', so it is THIS period, not a rollover-only clock. The rule it construes is §408(d)(3)(G)'s restriction on conversions; applying the same contribution-tracing to the RATE is this engine's reading of it. It runs BOTH ways. Dollars traceable to a prior employer whose period has EXPIRED keep that expiry and are NOT pulled into the new employer's open window. Dollars traceable to a prior employer whose period is STILL OPEN carry it into the new account and stay at 25%/6% even after the receiving employer's own window closes — until that prior period itself expires, not indefinitely. Where provenance cannot be substantiated, treat the amount as still inside a 2-year period (25%/6% — federal and CA respectively; NY has no analogous additional tax) rather than assuming the lower rate. |
| pensionDistributionIsNonqualifiedAnnuityNiiboolean | NOT the same contract as the federal endpoint — on /state this field is REQUIRED (else ny_private_pension_exclusion_classification_needed decline) whenever…NOT the same contract as the federal endpoint — on /state this field is REQUIRED (else ny_private_pension_exclusion_classification_needed decline) whenever nyPrivatePensionQualifiesFor20kExclusion:true is claimed on a positive pension, UNCONDITIONALLY, regardless of whether federal §1411 NIIT materiality would independently require it — NY IT-201-I's own negative list for the line-29 $20,000 exclusion excludes a nonqualified commercial annuity, a fact the federal-only materiality gate can leave unaffirmed below the NIIT threshold. true (a nonqualified commercial annuity) is also flatly inconsistent with nyPensionIsGovernmentPension:true or nyPrivatePensionQualifiesFor20kExclusion:true → decline (pension_exclusion_classification_ambiguous), and with CA's caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true → decline (ca_pension_exclusion_classification_ambiguous). IL: must be false to use ilPensionIsQualifiedRetirementIncomeAffirmed (else il_needs_review). |
| pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmedboolean | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true AND pensionDistributionIsNonqualifiedAnnuityNii is NOT explicitly false — see the federal endpoint's own field description for the full §72(q)(2) accept-list citation. |
| pensionDistributionEarlyWithdrawalBasisIsAvailableForThisPlanTypeAffirmedboolean | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — see the federal endpoint's own field description for the full plan-type-divergence citation. |
| pensionDistributionNoSeppModificationRecaptureAffirmedtrue | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — see the federal endpoint's own field description for the full SEPP-modification-recapture citation. |
| socialSecurityBenefitsnumber | Social Security benefits (SSA-1099 box 5, box 3 less box 4).Social Security benefits (SSA-1099 box 5, box 3 less box 4). CA, NY, IL, NC and MI FULLY EXCLUDE taxable Social Security: the engine recomputes the federal §86 taxable portion (line 6b) in-process and SUBTRACTS it on Schedule CA (540) line 6 col B (CA) / IT-201 line 27 (NY) / IL-1040 line 5 / D-400 line 9 / MI-1040 line 13. REQUIRES socialSecurityStandardCaseAffirmed:true (and socialSecurityMfsLivedWithSpouse for MFS) — the SAME §86 gates as the federal endpoint; an unaffirmed SS return declines federally → declines the state. |
| taxExemptInterestnumber | Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand.Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand. IL, NC and MI: REQUIRED (0 if none), added in full (IL-1040 line 2, D-400 line 7, MI-1040 line 11). CA/NY: accepted so the federal §86 recompute is correct, BUT any positive amount DECLINES the state return (state_tax_exempt_interest_unsupported): the CA out-of-state-muni add-back (Schedule CA line 2 col C) / NY non-NY-muni add-back (IT-225 A-101) is not sized in this slice. |
| socialSecurityStandardCaseAffirmedtrue | §6694 affirmation REQUIRED when socialSecurityBenefits is supplied:§6694 affirmation REQUIRED when socialSecurityBenefits is supplied: attests the standard §86 worksheet applies (no lump-sum election, no Form 8815, §137, §85(c), foreign-earned-income or §931-933 add-backs, no Roth-conversion or other provisional-income complications the engine does not model). Absent → declines (fail-closed). |
| socialSecurityMfsLivedWithSpouseboolean | REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately:REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately: whether the taxpayer lived with their spouse at any time during the year (§86(c)(1)(C) sets the MFS base amount to $0 if true). Absent for MFS+SS → declines. |
| noForeignOrTerritoryExclusionAffirmedbooleanrequired | Same as FederalProfile.noForeignOrTerritoryExclusionAffirmed; false declines a CA, NY, IL, NC or MI return (as federal_declined). |
| taxExemptInterestNoPrivateActivityBondstrue | §6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g).§6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g). Required with a positive taxExemptInterest on IL, NC and MI; on CA/NY a positive amount declines regardless. |
| estateTrustK1NoAmtAdjustmentAffirmedtrue | §6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest.§6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest. WHAT `true` ATTESTS: no Schedule K-1 (Form 1041) received for this tax year, from any estate or trust, shows a positive amount in box 12 code A (adjustment for minimum tax purposes, Form 6251 line 2j) or any amount, positive or negative, in box 12 codes B through I. Attest true if no such K-1 was received, or if every code A amount is zero or negative and codes B through I are blank on all of them (a negative code A left out over-states the tax). The engine sets line 2j to $0. Absent or false with any of those inputs: the return declines (estate_trust_amt_adjustment_unmodeled); true with none of them: declined as an orphan; false always declines (a preparer completes Form 6251). Never default it. Not detected: a K-1 with a code A or B-I amount but no income boxes, on a return with none of those inputs. |
| otherIncomePresentButUnmodeledarray of string | Same as FederalProfile.otherIncomePresentButUnmodeled; on /state the decline arrives as federal_declined. |
| stateenum (14 values)required | ca, ny, il, nc, mi, or a no-income-tax state ($0 or a decline). Any other state is rejected. |
| canBeClaimedAsDependentbooleanrequired | Required. true when another taxpayer can claim this filer (on a joint return, either spouse) as a dependent; CA, NY and IL decline true (dependent_filer_needs_review); NC and MI compute a single or…Required. true when another taxpayer can claim this filer (on a joint return, either spouse) as a dependent; CA, NY and IL decline true (dependent_filer_needs_review); NC and MI compute a single or married_filing_separately dependent filer who claims no dependents (NC full standard deduction; MI $1,500), and a no-income-tax state's $0 is unchanged. |
| residency"full_year_resident" | "part_year_resident" | "part_year" | "nonresident" | "non_resident" | Residency for the year; only a full-year resident computes, part-year and nonresident decline. |
| dependentsinteger | Number of dependent exemptions (CA Form 540 line 10; NY IT-201 line 36). Default 0. |
| seniorExemptionsinteger | CA only — senior (65+) exemptions (Form 540 line 9), 0–2. Default 0. |
| blindExemptionsinteger | CA only — blind exemptions (Form 540 line 8), 0–2. Default 0. |
| scheduleCIncomenumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.scheduleCIncome. |
| scheduleCIsSingleSolePropFinalNetAffirmedtrue | Same as FederalProfile.scheduleCIsSingleSolePropFinalNetAffirmed. |
| scheduleCNoAmtAdjustmentAffirmedtrue | Same as FederalProfile.scheduleCNoAmtAdjustmentAffirmed. |
| socialSecurityWagesnumber | Same as FederalProfile.socialSecurityWages. |
| caScheduleCSelfEmployedForCaPurposesAffirmedtrue | CA only — §6694 affirmation REQUIRED with a Schedule C net on the CA return.CA only — §6694 affirmation REQUIRED with a Schedule C net on the CA return. Attests the taxpayer is SELF-EMPLOYED FOR CALIFORNIA PURPOSES (NOT reclassified as an employee under AB5 / the Dynamex ABC test). CA disallows the §164(f) one-half-SE-tax deduction for a federal contractor who is a CA employee (Schedule CA 540 line 15) → taking federal AGI would under-tax by the half-SE amount; the engine cannot see CA worker classification, so absent/false → CA declines. Also requires caScheduleCNoStateBusinessAdjustmentsAffirmed. |
| caScheduleCNoStateBusinessAdjustmentsAffirmedtrue | CA only — §6694 affirmation REQUIRED with a Schedule C net on the CA return (Codex R251-001).CA only — §6694 affirmation REQUIRED with a Schedule C net on the CA return (Codex R251-001). Attests the federal Schedule C net has ZERO California business-income adjustments (Schedule CA 540 line 3 / FTB Pub 1001): no CA/federal depreciation or §179 difference (CA §179 cap is $25,000; CA does not conform to bonus depreciation), no PPP/EIDL/grant/loan-forgiveness exclusion difference, no fringe-benefit / accelerated-write-off / other Pub-1001 business-income or basis adjustment. AB5 classification alone is not sufficient — a CA line-3 addition the engine cannot see would under-tax; absent/false → CA declines (a preparer must make the Schedule CA line-3 adjustment). |
| caItemizedDeductionsnumber | CA only — the FINAL California Schedule CA (540) Part II line 30 itemized total, AFTER the CA state-and-local-income-tax disallowance (line 5a) AND the CA high-income itemized-deduction reduction worksheet (6% of AGI over the threshold).CA only — the FINAL California Schedule CA (540) Part II line 30 itemized total, AFTER the CA state-and-local-income-tax disallowance (line 5a) AND the CA high-income itemized-deduction reduction worksheet (6% of AGI over the threshold). NOT the federal Schedule A total (which is higher → would under-tax). Form 540 line 18 = greater-of(CA standard deduction, this). REQUIRES itemizedDeductionsAreFinalStateAmount:true (else declines); MFS declines (spouse's §63(c)(6)(A) election). The engine consumes it, does not derive or limit it. |
| itemizedDeductionsAreFinalStateAmounttrue | §6694 affirmation REQUIRED when caItemizedDeductions or nyItemizedDeductions is supplied:§6694 affirmation REQUIRED when caItemizedDeductions or nyItemizedDeductions is supplied: attests the amount is the FINAL state itemized total (CA Schedule CA line 30 / NY IT-196 line 49 — post state adjustments AND the state high-income limitation), NOT the federal Schedule A total. Absent → the itemized amount is DECLINED (fail-closed), preventing a silent federal-Schedule-A under-tax. |
| caWithholdingnumber | CA only — CA income tax withheld (Form 540 line 71). |
| caEstimatedPaymentsnumber | CA only — CA estimated tax payments (Form 540 line 72), excluding any prior-year overpayment applied. |
| caExtensionPaymentsnumber | CA only — CA payment made with an extension to file (FTB 3519). |
| caPriorYearOverpaymentnumber | CA only — Prior-year CA overpayment applied to this year (do not also count it in caEstimatedPayments). |
| w2Documentsarray of object | CA/NY only. Structured W-2 records (not PDFs). Box 15/16/17 can derive the state withholding (caWithholding / nyWithholding) only on a matching box-15 state; box 14 is surfaced for review and never…CA/NY only. Structured W-2 records (not PDFs). Box 15/16/17 can derive the state withholding (caWithholding / nyWithholding) only on a matching box-15 state; box 14 is surfaced for review and never changes the computation. |
| stateIncomeConformsToFederaltrue | CA/NY only (IL, NC and MI reject it) — §6694 whitelist affirmation:CA/NY only (IL, NC and MI reject it) — §6694 whitelist affirmation: ALL non-wage income is clean state-conforming (no tax-exempt/out-of-state-muni interest, no exempt-interest dividends OTHER THAN the out-of-state portion supplied as caOutOfStateMuniInterestAddition, no US-Treasury-obligation interest needing a CA subtraction OTHER THAN the explicitly-supplied caUsObligationInterestSubtraction (direct) or caUsObligationRicDividendSubtraction (RIC dividend, §17145), basis == federal). Required to compute non-wage income; absent → non-wage declines. |
| caUsObligationInterestSubtractionnumber | CA only — Schedule CA (540) Part I line 2 col B:CA only — Schedule CA (540) Part I line 2 col B: the US-government-obligation interest SUBTRACTION (R&TC §17143; US-Treasury interest is federally taxable but CA-exempt). Caller-asserted amount of the DIRECT US-obligation interest included in federal taxable interest (1040 line 2b), subtracted from CA AGI ONLY (not federal AGI). REQUIRES caUsObligationInterestAffirmed:true and is CAPPED at the supplied taxableInterest (exceeds → declines). A RIC/§17145 fund distribution is out of scope (declined). A subtraction over-claimed under-taxes → fails closed without the affirmation. |
| caUsObligationInterestAffirmedtrue | CA only — §6694 affirmation REQUIRED when caUsObligationInterestSubtraction is supplied:CA only — §6694 affirmation REQUIRED when caUsObligationInterestSubtraction is supplied: attests the amount is DIRECT US-Treasury/US-government-obligation interest included in your federal taxable interest (line 2b), NOT a RIC/mutual-fund (§17145) distribution, and ≤ that included interest. Absent → the subtraction declines. |
| caOutOfStateMuniInterestAdditionnumber | CA only — Schedule CA (540) Part I line 2 col C:CA only — Schedule CA (540) Part I line 2 col C: the OUT-OF-STATE municipal / exempt-interest-dividend interest ADDITION. Box-12 exempt-interest dividends (and any other tax-exempt interest) from NON-California municipal obligations are federally tax-exempt (never in federal AGI) but CA-taxable → ADDED to CA AGI ONLY (not federal AGI). CA munis AND US-territory munis (Puerto Rico/Guam/USVI, exempt in all states) stay CA-exempt and are EXCLUDED — BUT California's 50%-asset test makes the ENTIRE fund exempt-interest dividend CA-taxable (including the CA portion) when the fund holds <50% of assets in CA/US-territory/US-government obligations. REQUIRES caOutOfStateMuniInterestAffirmed:true (else declines). An addition is over-tax-safe; there is NO engine-visible cap (exempt-interest dividends never enter federal AGI), so the affirmation is the sole guard. NOT conformity-gated (a wages-only filer may supply it). |
| caOutOfStateMuniInterestAffirmedtrue | CA only — §6694 affirmation REQUIRED when caOutOfStateMuniInterestAddition is supplied:CA only — §6694 affirmation REQUIRED when caOutOfStateMuniInterestAddition is supplied: attests the amount is the CA-taxable portion of your box-12 exempt-interest dividends / tax-exempt interest — normally the portion from NON-California municipal obligations (CA munis AND US-territory munis — Puerto Rico/Guam/USVI — EXCLUDED), or the ENTIRE dividend when California's 50%-asset test fails. Absent → the addition declines. |
| caUsObligationRicDividendSubtractionnumber | CA only — Schedule CA (540) Part I line 2 col B:CA only — Schedule CA (540) Part I line 2 col B: the RIC/mutual-fund US-government-obligation DIVIDEND subtraction (R&TC §17145). A fund holding ≥50% of assets in US-government (and CA-exempt) obligations AT EACH QUARTER-END may pass the US-obligation-interest PORTION of its ORDINARY dividend (1099-DIV box 1a / line 3b) through as CA-exempt — this is the RIC case caUsObligationInterestSubtraction (direct interest, line 2b) declines. Subtracted from CA AGI ONLY (not federal AGI). REQUIRES the two-part caUsObligationRicDividendAffirmed:true and is CAPPED at non-qualified ordinary dividends (ordinaryDividends − qualifiedDividends; US-obligation interest is never a qualified dividend). The 50%-asset test is a CLIFF: below 50%, NONE is exempt (do not supply). A subtraction over-claimed under-taxes → fails closed without the affirmation. |
| caUsObligationRicDividendAffirmedtrue | CA only — §6694 TWO-PART affirmation REQUIRED when caUsObligationRicDividendSubtraction is supplied, attesting PER THE FUND'S OWN WRITTEN SHAREHOLDER TAX STATEMENT:CA only — §6694 TWO-PART affirmation REQUIRED when caUsObligationRicDividendSubtraction is supplied, attesting PER THE FUND'S OWN WRITTEN SHAREHOLDER TAX STATEMENT: (1) the amount is the US-government-obligation interest portion of the fund's ordinary dividend (1099-DIV box 1a) in your federal AGI, AND (2) the fund's statement affirms it MET California's ≥50%-US-obligation-assets-at-each-quarter test (§17145). Absent → the subtraction declines. |
| caHsaEmployerContributionAdditionnumber | CA only — Schedule CA (540) Part I Section A line 1h col C:CA only — Schedule CA (540) Part I Section A line 1h col C: HSA employer/cafeteria-plan contribution (W-2 box 12 code W), excluded from federal box-1 wages but CA-taxable (R&TC §17131.4, IRC §106(d); CA does not recognize HSAs). ADDED to CA AGI ONLY (never federal AGI). REQUIRES caHsaAddbacksAffirmed:true. Over-tax-safe (an addition). Do NOT also report it in wages. |
| caHsaInterestAdditionnumber | CA only — Schedule CA (540) Part I Section A line 2 col C:CA only — Schedule CA (540) Part I Section A line 2 col C: interest earned INSIDE an HSA (federally tax-deferred, CA-taxable in the year earned; §17215.4, IRC §223). ADDED to CA AGI ONLY. REQUIRES caHsaAddbacksAffirmed:true. Do NOT also report it in taxableInterest (double-count). |
| caHsaDividendAdditionnumber | CA only — Schedule CA (540) Part I Section A line 3 col C:CA only — Schedule CA (540) Part I Section A line 3 col C: taxable dividends earned INSIDE an HSA (CA-taxable in the year earned; §17215.4, IRC §223). ADDED to CA AGI ONLY. REQUIRES caHsaAddbacksAffirmed:true. Do NOT also report it in ordinaryDividends (double-count). NOTE: the SELF-contribution HSA deduction is NOT added back (the engine takes no federal HSA deduction to reverse); HSA distributions + Archer-MSA rollover (R&TC §17215, IRC §220, +12.5%) are out of scope, and so is the IRA-to-HSA one-time qualified-HSA-funding distribution — federally excluded under §408(d)(9)(A), but CA adds it back to CA AGI (and, where the distribution is premature under the §72(t) rules, a 2 1/2% additional tax) (§17215.4; FTB 3805P), so omitting THAT one UNDER-taxes CA. |
| caHsaAddbacksAffirmedtrue | CA only — §6694 affirmation REQUIRED when any caHsa*Addition is supplied:CA only — §6694 affirmation REQUIRED when any caHsa*Addition is supplied: attests each amount is the CA-taxable HSA add-back for its category and is NOT also reported in wages / taxableInterest / ordinaryDividends. Absent → the HSA add-backs decline (fail-closed). |
| caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmedboolean | CA only — §6694 affirmation, whole-scalar.CA only — §6694 affirmation, whole-scalar. true = the ENTIRE federal line-5b pensionDistributionTaxable amount is uniformed-services retirement pay (R&TC §17132.9) or a DoD Survivor Benefit Plan annuity payment (§17132.10). Excludes min($20,000, line 5b) from CA AGI, GATED on federal AGI — a HARD CLIFF per §17132.9(b)(1), not a phase-out — at ≤$250,000 for married_filing_jointly or ≤$125,000 for every other filing status; over the threshold, $0 is excluded. Absent/false → $0 excluded (NOT a decline — same over-tax-safe default as every other unaffirmed CA divergence). true is a flat contradiction with pensionDistributionIsNonqualifiedAnnuityNii:true (a self-funded commercial annuity cannot also be federal uniformed-services retired pay) → decline (ca_pension_exclusion_classification_ambiguous). Single-scalar cap: more than $20,000 of combined qualifying income in one year (e.g. both retired pay and a separate SBP annuity, or MFJ with two military retirees) is under-excluded (disclosed, safe, not modeled). No separate qualifying-surviving-spouse filing status exists on this engine, so a surviving spouse / named SBP beneficiary filing single/head_of_household with AGI between $125,000 and $250,000 under-computes safely; in this attestation, line 5b means all of pensionDistributionTaxable, IRA distributions included. |
| caPensionNoEarlyDistributionAdditionalTaxAffirmedtrue | CA only (founder decision D4, 2026-10-06).CA only (founder decision D4, 2026-10-06). REQUIRED whenever pensionDistributionTaxable is present. true attests that no California additional tax on an early distribution (R&TC §17085, FTB 3805P) is owed: each distribution was received at age 59½ or older, or under an exception California also allows. A distribution relying on a federal exception California does not adopt: do not attest. Absent or false: decline (ca_early_distribution_additional_tax_unmodeled); supplied with no pension: declined as an orphan. |
| caNoIraToHsaFundingDistributionAffirmedtrue | CA only (founder decision D4, 2026-10-06).CA only (founder decision D4, 2026-10-06). REQUIRED whenever pensionDistributionTaxable is present. true attests that no IRA-to-HSA qualified funding distribution (IRC §408(d)(9)) was made this year; California does not conform, so it is CA income (and may owe CA additional tax), which this engine does not compute: computing without it would under-tax. Absent or false: decline (ca_early_distribution_additional_tax_unmodeled). Not detected: such a distribution on a CA return with no pensionDistributionTaxable. |
curl https://tax-mcp.com/api/mcp/tax-compute/state \
-H "Authorization: Bearer $TAX_MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"state": "ca",
"year": 2025,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 80000,
"medicareWages": 80000,
"caWithholding": 5000
}'{
"computed": true,
"state": "ca",
"year": 2025,
"filingStatus": "single",
"stateAGI": 80000,
"stateDeductions": 5706,
"stateTaxableIncome": 74294,
"incomeTaxBeforeCredits": 3349,
"exemptionCredits": 153,
"incomeTax": 3196,
"additionalTaxes": [],
"totalTax": 3196,
"lines": [
{ "lineId": "540:13", "label": "Federal AGI", "amount": 80000, "agiRole": "agi_base" },
{
"lineId": "540:17",
"label": "CA adjusted gross income",
"amount": 80000,
"agiRole": "agi_total"
},
{
"lineId": "540:18",
"label": "CA standard deduction",
"amount": 5706,
"agiRole": "below_agi",
"cite": "<primary-source cite — see full response>"
},
{
"lineId": "540:19",
"label": "CA taxable income",
"amount": 74294,
"agiRole": "below_agi"
},
{
"lineId": "540:31",
"label": "CA tax (2025 California Tax Table)",
"amount": 3349,
"agiRole": "below_agi",
"cite": "<primary-source cite — see full response>"
},
{
"lineId": "540:32",
"label": "CA exemption credits",
"amount": 153,
"agiRole": "below_agi",
"cite": "<primary-source cite — see full response>"
},
{
"lineId": "540:33",
"label": "CA tax after exemption credits",
"amount": 3196,
"agiRole": "below_agi"
},
{ "lineId": "540:64", "label": "Total CA tax", "amount": 3196, "agiRole": "below_agi" }
],
"flags": [
"CA-AGI-assumed-equal-to-federal-AGI (wages-only; no Schedule CA 540 adjustments). A filer with CA-specific adjustments (HSA add-back, US-Treasury/out-of-state-muni interest, SS exclusion) needs Schedule CA 540.",
"CA-AMT-not-computed (Schedule P, R&TC §17062). A full-year resident with no AMT preference items owes regular CA tax; a filer with preference items (ISO, accelerated depreciation, etc.) must complete Schedule P.",
"CA-exemption-credits-computed-with personal/blind/senior=1 ($153 each), dependents=0 ($475 each); blind/senior/dependents default to 0 when not supplied — supply them if applicable.",
"CA payments = withholding $5,000 + estimated $0 + extension $0 + prior-year-overpayment-applied $0 = $5,000. These coexist, but must NOT double-count — caEstimatedPayments must NOT also include the prior-year overpayment (that double-counts and over-states the refund)."
],
"totalPayments": 5000,
"balanceDue": 0,
"overpayment": 1804,
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "ca", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "<computation-support notice — see full response>"
}
}Full response, including line derivations
{
"computed": true,
"state": "ca",
"year": 2025,
"filingStatus": "single",
"stateAGI": 80000,
"stateDeductions": 5706,
"stateTaxableIncome": 74294,
"incomeTaxBeforeCredits": 3349,
"exemptionCredits": 153,
"incomeTax": 3196,
"additionalTaxes": [],
"totalTax": 3196,
"lines": [
{ "lineId": "540:13", "label": "Federal AGI", "amount": 80000, "agiRole": "agi_base" },
{
"lineId": "540:17",
"label": "CA adjusted gross income",
"amount": 80000,
"agiRole": "agi_total"
},
{
"lineId": "540:18",
"label": "CA standard deduction",
"amount": 5706,
"agiRole": "below_agi",
"cite": {
"jurisdiction": "ca",
"cellKey": "std_deduction.2025.single",
"authority": "CA FTB 2025 Standard Deduction — R&TC §17073.5 (CPI-indexed)"
}
},
{
"lineId": "540:19",
"label": "CA taxable income",
"amount": 74294,
"agiRole": "below_agi"
},
{
"lineId": "540:31",
"label": "CA tax (2025 California Tax Table)",
"amount": 3349,
"agiRole": "below_agi",
"cite": {
"jurisdiction": "ca",
"cellKey": "brackets.2025.single",
"authority": "CA FTB 2025 Form 540 booklet 2025 California Tax Table (rate schedule at band midpoint; required when taxable income ≤ $100,000)"
}
},
{
"lineId": "540:32",
"label": "CA exemption credits",
"amount": 153,
"agiRole": "below_agi",
"cite": {
"jurisdiction": "ca",
"cellKey": "exemption_credit.2025.personal",
"authority": "CA FTB 2025 Form 540 lines 7–10 Exemption Credits — R&TC §17054 ($153 personal/blind/senior, $475 dependent)"
}
},
{
"lineId": "540:33",
"label": "CA tax after exemption credits",
"amount": 3196,
"agiRole": "below_agi"
},
{ "lineId": "540:64", "label": "Total CA tax", "amount": 3196, "agiRole": "below_agi" }
],
"flags": [
"CA-AGI-assumed-equal-to-federal-AGI (wages-only; no Schedule CA 540 adjustments). A filer with CA-specific adjustments (HSA add-back, US-Treasury/out-of-state-muni interest, SS exclusion) needs Schedule CA 540.",
"CA-AMT-not-computed (Schedule P, R&TC §17062). A full-year resident with no AMT preference items owes regular CA tax; a filer with preference items (ISO, accelerated depreciation, etc.) must complete Schedule P.",
"CA-exemption-credits-computed-with personal/blind/senior=1 ($153 each), dependents=0 ($475 each); blind/senior/dependents default to 0 when not supplied — supply them if applicable.",
"CA payments = withholding $5,000 + estimated $0 + extension $0 + prior-year-overpayment-applied $0 = $5,000. These coexist, but must NOT double-count — caEstimatedPayments must NOT also include the prior-year overpayment (that double-counts and over-states the refund)."
],
"totalPayments": 5000,
"balanceDue": 0,
"overpayment": 1804,
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "ca", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}
}Request body: New York
"state": "ny". 83 fields. nyWageAdditions is required to compute wages.
| Field | Description |
|---|---|
| yearintegerrequired | Tax year; a year the state engine does not model declines. |
| filingStatus"single" | "married_filing_jointly" | "married_filing_separately" | "head_of_household"required | REQUIRED. The state endpoint re-runs the FEDERAL pipeline to derive its starting point, so it needs the same filing status the federal endpoint does. |
| wagesnumber | Same as FederalProfile.wages. |
| medicareWagesnumber | Medicare wages (W-2 box 5). CONDITIONALLY REQUIRED, and the condition cannot be expressed in this schema's `required` array, which is why it is spelled out here. This endpoint re-runs the FEDERAL…Medicare wages (W-2 box 5). CONDITIONALLY REQUIRED, and the condition cannot be expressed in this schema's `required` array, which is why it is spelled out here. This endpoint re-runs the FEDERAL pipeline, and that pipeline declines its Additional Medicare Tax determination whenever box 5 is omitted AND at least one of the federal pipeline's W-2 evidence fields is POSITIVE (the trigger is a positive amount, not mere presence: an explicit 0 does not arm it). Those fields are `wages`, `federalWithholding`, `medicareTaxWithheld` and `socialSecurityWages`, and this endpoint accepts all four, so a positive value in any of them arms it. WHAT A STATE CALLER ACTUALLY RECEIVES: `computed:false` with code `federal_declined` - NOT the federal-side code `surtax_additional_medicare`, which this endpoint does not surface; the box-5 explanation arrives in `reason`. Rationale: box 5 can exceed box 1 by an unbounded amount for real filers - 401(k)/403(b)/457(b) elective deferrals reduce box 1 while remaining subject to Medicare tax - so no finite margin can rule out the Additional Medicare Tax threshold being crossed at box 5. It is NOT required in the absence of positive W-2 evidence: a dividends-only or zero-wage return computes without it. Declared because a caller building exactly what this schema prescribes must be able to learn this requirement from the schema itself. |
| federalWithholdingnumber | Same as FederalProfile.federalWithholding. |
| medicareTaxWithheldnumber | Same as FederalProfile.medicareTaxWithheld. |
| taxableInterestnumber | CA/NY: requires stateIncomeConformsToFederal:true (else non-wage income declines); IL, NC and MI take it without. |
| ordinaryDividendsnumber | CA/NY: requires stateIncomeConformsToFederal:true. |
| qualifiedDividendsnumber | ≤ ordinaryDividends; CA/NY/IL/NC/MI tax it as ordinary (no preferential rate); CA/NY require stateIncomeConformsToFederal:true. |
| reit199ADividendsnumber | Same as FederalProfile.reit199ADividends. |
| netShortTermCapGainnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Taxed as ordinary by CA/NY/IL/NC/MI; CA/NY require stateIncomeConformsToFederal:true. |
| netLongTermCapGainnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Taxed as ordinary by CA/NY/IL/NC/MI; CA/NY require stateIncomeConformsToFederal:true. |
| priorYearCapLossCarryoverSTnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year SHORT-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Applied with the §1211(b) −$3,000 (−$1,500 MFS) annual limit. THIS ENDPOINT DOES NOT RETURN AN ENDING CARRYOVER: endingCapLossCarryoverST is a FEDERAL-response field and the state response has no equivalent, so track the remaining carryover yourself or read it from /federal. This field is the PRIOR-YEAR carryover only — do NOT also net it into netShortTermCapGain/netLongTermCapGain, which are CURRENT-YEAR nets before any carryover; doing both applies it twice (an executed $12,120 under-tax). Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. Accepted on the STATE endpoint for the same reason: this endpoint re-runs the federal pipeline, so this field's presence arms the identical Schedule-D-presence affirmation gates described above, and a caller who omits a zero-net carryover here bypasses them exactly as on /federal. If only an AMT-side carryover exists, send 0 (the return declines). |
| priorYearCapLossCarryoverLTnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year LONG-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Nets against long-term gain. THIS ENDPOINT DOES NOT RETURN AN ENDING CARRYOVER: endingCapLossCarryoverLT is a FEDERAL-response field and the state response has no equivalent, so track the remaining carryover yourself or read it from /federal. Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. Accepted on the STATE endpoint for the same reason: this endpoint re-runs the federal pipeline, so this field's presence arms the identical Schedule-D-presence affirmation gates described above, and a caller who omits a zero-net carryover here bypasses them exactly as on /federal. If only an AMT-side carryover exists, send 0 (the return declines). |
| capLossCarryoverNoAmtDifferenceAffirmedtrue | §6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the trigger is PRESENCE, not magnitude, and not the carryover field specifically.§6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the trigger is PRESENCE, not magnitude, and not the carryover field specifically. WHAT `true` ATTESTS (identical to FederalProfile.capLossCarryoverNoAmtDifferenceAffirmed): EITHER (a) this return has no prior-year capital-loss carryover at all, for regular tax or AMT — the common case, and attesting true is how you say so — OR (b) a carryover exists and its ENTERING AMT-SIDE amount equals its regular-tax amount. It covers a carryover HOWEVER it reached this engine, including one the caller already netted into netShortTermCapGain/netLongTermCapGain, and it additionally attests the carryover was NOT supplied BOTH ways (netted into a scalar AND as priorYearCapLossCarryover*), which would apply it twice. DO NOT SUPPLY IT DEFENSIVELY: on a return carrying NO Schedule D input at all this is a contradictory orphan affirmation and the return is DECLINED - a state caller receives `computed:false` with code `federal_declined`, the orphan explanation in `reason`. An AMT-only carryover is NOT covered: send priorYearCapLossCarryoverST/LT as 0, and the return declines. |
| mortgageInterestnumber | Same as FederalProfile.mortgageInterest. |
| mortgageAvgBalancenumber | Same as FederalProfile.mortgageAvgBalance. |
| mortgageInterestExcludesExcessRefinancingProceedsboolean | Same as FederalProfile.mortgageInterestExcludesExcessRefinancingProceeds. |
| mortgageInterestSecuresAmtQualifiedDwellingboolean | Same as FederalProfile.mortgageInterestSecuresAmtQualifiedDwelling. |
| mortgageInterestSecuresSec121PrincipalResidenceboolean | Same as FederalProfile.mortgageInterestSecuresSec121PrincipalResidence. |
| foreignTaxPaidnumber | Same as FederalProfile.foreignTaxPaid. |
| foreignIncomeAllPassive1099true | Same as FederalProfile.foreignIncomeAllPassive1099: all foreign income is passive and shown on a qualified payee statement (§6724(d)(2)), which is broader than the 1099 family. |
| foreignTaxIsFullyCreditableAffirmedtrue | Same as FederalProfile.foreignTaxIsFullyCreditableAffirmed. |
| foreignSourceGrossIncomenumber | Same as FederalProfile.foreignSourceGrossIncome. |
| foreignQualifiedDividendsAndCapGainsnumber | Same as FederalProfile.foreignQualifiedDividendsAndCapGains. |
| foreignTaxNoCarryoverAffirmedtrue | Same as FederalProfile.foreignTaxNoCarryoverAffirmed. |
| foreignSourceNoForm1116PartILines2Through5EntryAffirmedtrue | Same as FederalProfile.foreignSourceNoForm1116PartILines2Through5EntryAffirmed. |
| foreignSourceNoForm1116Line16AdjustmentAffirmedtrue | Same as FederalProfile.foreignSourceNoForm1116Line16AdjustmentAffirmed. |
| foreignTaxNoForm1116Line12ReductionAffirmedtrue | Same as FederalProfile.foreignTaxNoForm1116Line12ReductionAffirmed. |
| stateLocalIncomeTaxnumber | Same as FederalProfile.stateLocalIncomeTax. |
| realEstateTaxnumber | Same as FederalProfile.realEstateTax. |
| sec1250UnrecapturedGainnumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.sec1250UnrecapturedGain. |
| collectibles28Gainnumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.collectibles28Gain. |
| specialRateGainNoAmtScheduleDDifferenceAffirmedboolean | Same as FederalProfile.specialRateGainNoAmtScheduleDDifferenceAffirmed. |
| collectibles28NoSec1202ExclusionPreferenceAffirmedtrue | §6694 affirmation REQUIRED on the same Schedule-D-presence trigger.§6694 affirmation REQUIRED on the same Schedule-D-presence trigger. WHAT `true` ATTESTS (identical to FederalProfile.collectibles28NoSec1202ExclusionPreferenceAffirmed): EITHER no §1202 qualified-small-business-stock exclusion is involved on this return at all, OR every §1202 exclusion claimed arises solely from stock acquired AFTER 2010-09-27 and so carries no §57(a)(7) AMT preference. This engine hardcodes AMT other-preferences to $0, so an unattested pre-2010-09-28 exclusion would UNDER-state AMT — and the preference is 7% of the EXCLUDED gain, which no input here carries and which netting cannot reduce, so it survives even when every capital-gain figure on the return nets to $0. That is why the trigger is presence of Schedule D activity rather than a positive amount. DO NOT SUPPLY IT DEFENSIVELY: on a return carrying NO Schedule D input at all this is a contradictory orphan affirmation and the return is DECLINED - a state caller receives `computed:false` with code `federal_declined`, the orphan explanation in `reason`. |
| qbiDeductionnumber | Same as FederalProfile.qbiDeduction; on /state the decline arrives as federal_declined. |
| pensionDistributionTaxablenumber | State (CA, NY, IL, NC, MI) — the fully-taxable federal line-4b/5b pension/IRA distribution (with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true).State (CA, NY, IL, NC, MI) — the fully-taxable federal line-4b/5b pension/IRA distribution (with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true). IL subtracts it with ilPensionIsQualifiedRetirementIncomeAffirmed; NC taxes it (its retirement deductions are not modeled, an over-tax); MI: see miNoRetirementOrAgeDeductionsAffirmed and miRetirementFactsAffirmed. NY EXCLUDES it: supply nyPensionIsGovernmentPension (IT-201 line 26, full) OR nyPrivatePensionQualifiesFor20kExclusion (IT-201 line 29, min($20k,5b)); neither → the pension stays NY-taxable. CA CONFORMS and TAXES it by default, with ONE modeled exclusion: caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true excludes min($20,000, line 5b), AGI-gated (R&TC §§17132.9/17132.10) — and a VERIFY flag names the unmodeled CA divergences enumerated in CA_COMPUTE_CAPABILITY.state_adjustments.pension (served on GET /api/mcp/tax-compute/state), which is the single authoritative list — this text states no count of its own, because a count restated in many places is a claim that must be maintained in many places, and on this surface it was not. (1) Tier-2 railroad retirement (RRB-1099-R), which CA EXCLUDES (45 U.S.C. §231m) — omitting it OVER-taxes. (2) CA's early-distribution additional tax, which this engine computes for NEITHER jurisdiction: 2.5% (R&TC §17085(c)(1)), raised to 6% where §72(t)(6) applies (§17085(c)(2), FTB 3805P line 4), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax — omitting THIS one UNDER-taxes. (3) An IRA-to-HSA one-time funding distribution under §408(d)(9), EXCLUDED from federal gross income under §408(d)(9)(A) but which California conforms out entirely (R&TC §17215.4) — the FTB 3805P instructions require it ADDED BACK to CA AGI, and — where the distribution is premature under the §72(t) rules — a 2 1/2% additional tax, which can be owed even where no federal §72(t) tax is. This one runs the OPPOSITE way from (1): omitting it UNDER-taxes California, and the engine has no field for it, so a CA return carrying one is outside the modeled surface. |
| pensionDistributionFullyTaxableAffirmedtrue | §6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint, one of TWO required affirmations):§6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint, one of TWO required affirmations): the fully-taxable 1099-R box 2a distribution, no basis/QCD/rollover/Roth/NUA. |
| pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmedtrue | §6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed (same contract as the federal endpoint).§6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed (same contract as the federal endpoint). THIS SCHEMA DELIBERATELY DOES NOT RESTATE THE RULE — see the federal endpoint's field of this name for the operative condition, which GOVERNS. (fed-pension-5b-72q-levy-exception-fix, 2026-08-29 — see the federal endpoint's pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmed field, required on the SAME contract here whenever this field is true and pensionDistributionIsNonqualifiedAnnuityNii is not explicitly false; and pensionDistributionNoSeppModificationRecaptureAffirmed, required on the SAME contract here whenever this field is true — regardless of which specific basis — per fed-pension-5b-sepp-modification-recapture-gate, 2026-08-29). SIMPLE-IRA timing within the §72(t)(6)(A) 2-year period does not by itself disqualify a 59½+ or exception-covered distribution — it only affects the RATE of a genuinely early, no-exception distribution, which this engine does not compute. CALIFORNIA DIVERGES on that rate and this engine computes it for neither jurisdiction: CA's analogue is 2.5% (R&TC §17085(c)(1)), 6% where §72(t)(6) applies (§17085(c)(2)), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax. THE 2-YEAR CLOCK IS ANCHORED TO PARTICIPATION IN THE EMPLOYER'S PLAN, NOT THE ACCOUNT'S AGE: §72(t)(6)(A) runs the period from 'the date such individual first participated in any qualified salary reduction arrangement maintained by the individual's employer under section 408(p)(2)', and IRS Notice 98-4 Q&A I-5 gives the operational start — 'the first day on which contributions made by the individual's employer are deposited in the individual's SIMPLE IRA' (the Form 5329 instructions and FTB 3805P agree). It is measured PER EMPLOYER, so a new employer's SIMPLE starts a NEW 2-year period for that employer's own contributions — reading the clock as the ACCOUNT's age can UNDER-tax at 10%/2.5%. A transfer or rollover between SIMPLE IRAs under the SAME employer's arrangement does not restart it. ACROSS EMPLOYERS THE PERIOD FOLLOWS EACH EMPLOYER'S OWN CONTRIBUTIONS — 26 CFR §1.408A-4 A-4(b): 'This 2-year period of section 408(d)(3)(G) applies separately to the contributions of each of an individual's employers maintaining a SIMPLE IRA Plan' — and A-4(b) itself identifies that period as 'the 2-year period described in section 72(t)(6)', so it is THIS period, not a rollover-only clock. The rule it construes is §408(d)(3)(G)'s restriction on conversions; applying the same contribution-tracing to the RATE is this engine's reading of it. It runs BOTH ways. Dollars traceable to a prior employer whose period has EXPIRED keep that expiry and are NOT pulled into the new employer's open window. Dollars traceable to a prior employer whose period is STILL OPEN carry it into the new account and stay at 25%/6% even after the receiving employer's own window closes — until that prior period itself expires, not indefinitely. Where provenance cannot be substantiated, treat the amount as still inside a 2-year period (25%/6% — federal and CA respectively; NY has no analogous additional tax) rather than assuming the lower rate. |
| pensionDistributionIsNonqualifiedAnnuityNiiboolean | NOT the same contract as the federal endpoint — on /state this field is REQUIRED (else ny_private_pension_exclusion_classification_needed decline) whenever…NOT the same contract as the federal endpoint — on /state this field is REQUIRED (else ny_private_pension_exclusion_classification_needed decline) whenever nyPrivatePensionQualifiesFor20kExclusion:true is claimed on a positive pension, UNCONDITIONALLY, regardless of whether federal §1411 NIIT materiality would independently require it — NY IT-201-I's own negative list for the line-29 $20,000 exclusion excludes a nonqualified commercial annuity, a fact the federal-only materiality gate can leave unaffirmed below the NIIT threshold. true (a nonqualified commercial annuity) is also flatly inconsistent with nyPensionIsGovernmentPension:true or nyPrivatePensionQualifiesFor20kExclusion:true → decline (pension_exclusion_classification_ambiguous), and with CA's caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true → decline (ca_pension_exclusion_classification_ambiguous). IL: must be false to use ilPensionIsQualifiedRetirementIncomeAffirmed (else il_needs_review). |
| pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmedboolean | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true AND pensionDistributionIsNonqualifiedAnnuityNii is NOT explicitly false — see the federal endpoint's own field description for the full §72(q)(2) accept-list citation. |
| pensionDistributionEarlyWithdrawalBasisIsAvailableForThisPlanTypeAffirmedboolean | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — see the federal endpoint's own field description for the full plan-type-divergence citation. |
| pensionDistributionNoSeppModificationRecaptureAffirmedtrue | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — see the federal endpoint's own field description for the full SEPP-modification-recapture citation. |
| socialSecurityBenefitsnumber | Social Security benefits (SSA-1099 box 5, box 3 less box 4).Social Security benefits (SSA-1099 box 5, box 3 less box 4). CA, NY, IL, NC and MI FULLY EXCLUDE taxable Social Security: the engine recomputes the federal §86 taxable portion (line 6b) in-process and SUBTRACTS it on Schedule CA (540) line 6 col B (CA) / IT-201 line 27 (NY) / IL-1040 line 5 / D-400 line 9 / MI-1040 line 13. REQUIRES socialSecurityStandardCaseAffirmed:true (and socialSecurityMfsLivedWithSpouse for MFS) — the SAME §86 gates as the federal endpoint; an unaffirmed SS return declines federally → declines the state. |
| taxExemptInterestnumber | Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand.Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand. IL, NC and MI: REQUIRED (0 if none), added in full (IL-1040 line 2, D-400 line 7, MI-1040 line 11). CA/NY: accepted so the federal §86 recompute is correct, BUT any positive amount DECLINES the state return (state_tax_exempt_interest_unsupported): the CA out-of-state-muni add-back (Schedule CA line 2 col C) / NY non-NY-muni add-back (IT-225 A-101) is not sized in this slice. |
| socialSecurityStandardCaseAffirmedtrue | §6694 affirmation REQUIRED when socialSecurityBenefits is supplied:§6694 affirmation REQUIRED when socialSecurityBenefits is supplied: attests the standard §86 worksheet applies (no lump-sum election, no Form 8815, §137, §85(c), foreign-earned-income or §931-933 add-backs, no Roth-conversion or other provisional-income complications the engine does not model). Absent → declines (fail-closed). |
| socialSecurityMfsLivedWithSpouseboolean | REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately:REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately: whether the taxpayer lived with their spouse at any time during the year (§86(c)(1)(C) sets the MFS base amount to $0 if true). Absent for MFS+SS → declines. |
| noForeignOrTerritoryExclusionAffirmedbooleanrequired | Same as FederalProfile.noForeignOrTerritoryExclusionAffirmed; false declines a CA, NY, IL, NC or MI return (as federal_declined). |
| taxExemptInterestNoPrivateActivityBondstrue | §6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g).§6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g). Required with a positive taxExemptInterest on IL, NC and MI; on CA/NY a positive amount declines regardless. |
| estateTrustK1NoAmtAdjustmentAffirmedtrue | §6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest.§6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest. WHAT `true` ATTESTS: no Schedule K-1 (Form 1041) received for this tax year, from any estate or trust, shows a positive amount in box 12 code A (adjustment for minimum tax purposes, Form 6251 line 2j) or any amount, positive or negative, in box 12 codes B through I. Attest true if no such K-1 was received, or if every code A amount is zero or negative and codes B through I are blank on all of them (a negative code A left out over-states the tax). The engine sets line 2j to $0. Absent or false with any of those inputs: the return declines (estate_trust_amt_adjustment_unmodeled); true with none of them: declined as an orphan; false always declines (a preparer completes Form 6251). Never default it. Not detected: a K-1 with a code A or B-I amount but no income boxes, on a return with none of those inputs. |
| otherIncomePresentButUnmodeledarray of string | Same as FederalProfile.otherIncomePresentButUnmodeled; on /state the decline arrives as federal_declined. |
| stateenum (14 values)required | ca, ny, il, nc, mi, or a no-income-tax state ($0 or a decline). Any other state is rejected. |
| canBeClaimedAsDependentbooleanrequired | Required. true when another taxpayer can claim this filer (on a joint return, either spouse) as a dependent; CA, NY and IL decline true (dependent_filer_needs_review); NC and MI compute a single or…Required. true when another taxpayer can claim this filer (on a joint return, either spouse) as a dependent; CA, NY and IL decline true (dependent_filer_needs_review); NC and MI compute a single or married_filing_separately dependent filer who claims no dependents (NC full standard deduction; MI $1,500), and a no-income-tax state's $0 is unchanged. |
| residency"full_year_resident" | "part_year_resident" | "part_year" | "nonresident" | "non_resident" | Residency for the year; only a full-year resident computes, part-year and nonresident decline. |
| dependentsinteger | Number of dependent exemptions (CA Form 540 line 10; NY IT-201 line 36). Default 0. |
| qualifyingChildrenUnder4integer | NY only — qualifying children under age 4, for the Empire State Child Credit. |
| qualifyingChildren4to16integer | NY only — qualifying children aged 4 to 16, for the Empire State Child Credit. |
| nycResidentboolean | NY only — true if the filer was a full-year New York City resident (adds NYC resident tax). |
| nyWageAdditionsnumber | NY only — 414(h)/IRC-125 add-backs (NY fails closed without it) |
| nyItemizedDeductionsnumber | NY only — the FINAL New York Form IT-196 line 49 itemized total, AFTER the NY state/local income-tax ADDBACK and the NY high-income itemized LIMITATION worksheet (IT-196-I line 47:NY only — the FINAL New York Form IT-196 line 49 itemized total, AFTER the NY state/local income-tax ADDBACK and the NY high-income itemized LIMITATION worksheet (IT-196-I line 47: itemized limited to 50% of line-19 gifts-to-charity for NYAGI $1,000,000–$10,000,000, and 25% of line 19 for NYAGI over $10,000,000; line 48 then adds the college-tuition itemized deduction). NOT the federal Schedule A total (which is higher → would under-tax). IT-201 line 34 = greater-of(NY standard deduction, this). REQUIRES itemizedDeductionsAreFinalStateAmount:true (else declines); MFS declines (spouse's §63(c)(6)(A) election). The engine consumes it, does not derive, verify, or apply the IT-196 limitation. |
| itemizedDeductionsAreFinalStateAmounttrue | §6694 affirmation REQUIRED when caItemizedDeductions or nyItemizedDeductions is supplied:§6694 affirmation REQUIRED when caItemizedDeductions or nyItemizedDeductions is supplied: attests the amount is the FINAL state itemized total (CA Schedule CA line 30 / NY IT-196 line 49 — post state adjustments AND the state high-income limitation), NOT the federal Schedule A total. Absent → the itemized amount is DECLINED (fail-closed), preventing a silent federal-Schedule-A under-tax. |
| nyWithholdingnumber | NY only — NY (and NYC) income tax withheld (IT-201 line 72). |
| nyEstimatedPaymentsnumber | NY only — NY estimated tax payments (IT-201 line 75), excluding any prior-year overpayment applied. |
| nyExtensionPaymentsnumber | NY only — NY payment made with an extension to file (IT-370). |
| nyPriorYearOverpaymentnumber | NY only — Prior-year NY overpayment applied to this year (do not also count it in nyEstimatedPayments). |
| w2Documentsarray of object | CA/NY only. Structured W-2 records (not PDFs). Box 15/16/17 can derive the state withholding (caWithholding / nyWithholding) only on a matching box-15 state; box 14 is surfaced for review and never…CA/NY only. Structured W-2 records (not PDFs). Box 15/16/17 can derive the state withholding (caWithholding / nyWithholding) only on a matching box-15 state; box 14 is surfaced for review and never changes the computation. |
| stateIncomeConformsToFederaltrue | CA/NY only (IL, NC and MI reject it) — §6694 whitelist affirmation:CA/NY only (IL, NC and MI reject it) — §6694 whitelist affirmation: ALL non-wage income is clean state-conforming (no tax-exempt/out-of-state-muni interest, no exempt-interest dividends OTHER THAN the out-of-state portion supplied as caOutOfStateMuniInterestAddition, no US-Treasury-obligation interest needing a CA subtraction OTHER THAN the explicitly-supplied caUsObligationInterestSubtraction (direct) or caUsObligationRicDividendSubtraction (RIC dividend, §17145), basis == federal). Required to compute non-wage income; absent → non-wage declines. |
| nyPensionIsGovernmentPensiontrue | NY only — §6694 affirmation for the IT-201 line 26 GOVERNMENT-pension FULL exclusion (§612(c)(3)):NY only — §6694 affirmation for the IT-201 line 26 GOVERNMENT-pension FULL exclusion (§612(c)(3)): attests the ENTIRE federal line-5b amount is a NYS/local-NY/federal government-EMPLOYER pension (incl. U.S. military, its territories/possessions or any political subdivision thereof, or the District of Columbia), NO private/IRA/annuity component. ALSO covers a nonemployee spouse's distribution from a NY State/local or federal government pension plan under a court-issued QDRO or NY-court DRO — IT-201-I extends line 26 (not just the capped line-29 path) to this case. Per IT-201-I, IRC §457 GOVERNMENT deferred-comp is EXPLICITLY NOT a line-26 item (it goes to the line-29 private $20k path) — do NOT affirm this for a §457 distribution. ORP PORTION LIMIT: an Optional Retirement Program participant may only affirm this for the portion attributable to SUNY/CUNY/NYSED employment -- a MIXED ORP distribution (part SUNY/CUNY/NYSED, part other employer) must NOT affirm the whole scalar, and must ALSO affirm nyGovernmentPensionNotOrpOrEntirelySunyCunyNysedAttributableAffirmed:true — absent/false declines (ny_pension_orp_portion_unsupported). NY excludes 100% (uncapped). Line 5b is a single scalar → a mixed govt+private (or govt+§457) 5b must NOT affirm (→ pension taxed, or a preparer splits). Mutually exclusive with nyPrivatePensionQualifiesFor20kExclusion (both → decline); in this attestation, line 5b means all of pensionDistributionTaxable, IRA distributions included. |
| nyGovernmentPensionNotOrpOrEntirelySunyCunyNysedAttributableAffirmedtrue | NY only — §6694 affirmation, REQUIRED whenever nyPensionIsGovernmentPension:true is claimed.NY only — §6694 affirmation, REQUIRED whenever nyPensionIsGovernmentPension:true is claimed. Attests EITHER this pension is not from an Optional Retirement Program (ORP) at all, OR it is an ORP distribution and the ENTIRE federal line-5b amount is attributable to employment with SUNY/CUNY/NYSED specifically. This engine cannot isolate a partial SUNY/CUNY/NYSED-attributable amount from a mixed ORP distribution's single line-5b scalar, so a genuinely mixed ORP distribution cannot truthfully affirm either branch and must decline (ny_pension_orp_portion_unsupported) — a preparer splits the sources. Absent/false → decline (fail-closed); in this attestation, line 5b means all of pensionDistributionTaxable, IRA distributions included. |
| nyPrivatePensionQualifiesFor20kExclusiontrue | NY only — §6694 affirmation for the IT-201 line 29 PRIVATE pension/annuity exclusion (§612(c)(3-a), up to $20,000):NY only — §6694 affirmation for the IT-201 line 29 PRIVATE pension/annuity exclusion (§612(c)(3-a), up to $20,000): attests (a) for a pension the recipient OWNS (not inherited — see nyPrivatePensionIsEntirelyRecipientsOwnNotInheritedAffirmed below), the recipient was age 59½ BEFORE January 1, 2025 (a taxpayer who became 59½ during 2025 must NOT affirm HERE — which is a limit of THIS ENGINE, not of the exclusion: IT-201-I says 'if you became 59½ during 2025, enter only the amount you received after you became 59½', so such a taxpayer IS entitled to the exclusion on the post-birthday portion. This engine receives a single federal line-5b figure it cannot split by date, so it requires the stricter whole-year condition and a preparer must handle the split case by hand. Over-decline, never an under-tax), AND (b) the ENTIRE federal line-5b amount is qualifying pension/annuity income per IT-201-I's PER-SOURCE periodic/lump-sum matrix (NOT a uniform 'periodic-only' rule): an IRA distribution qualifies periodic OR lump-sum with no restriction; a Keogh (HR-10) distribution qualifies periodic OR lump-sum, but a lump-sum Keogh distribution qualifies ONLY IF Form 4972 is NOT used; an IRC §457 government deferred-comp, an IRC §403(b) annuity-contract, or a cafeteria plan (IRC §125) / profit-sharing-or-stock-bonus plan (IRC §401(k)) distribution is PERIODIC-ONLY (no Form-4972-style escape valve for a lump sum from any of these three); an ORDINARY employer pension (IT-201-I's own first line-29 bullet, "periodic payments for services you performed as an employee before you retired") is ALSO PERIODIC-ONLY, same rule as §457/§403(b)/cafeteria-§401(k) -- and, independent of that axis, no contributions made after the recipient retired to an IRA, a Keogh (HR-10) plan, a cafeteria plan (IRC §125), or a profit-sharing/stock-bonus plan (IRC §401(k)), and NONE of IT-201-I's line-29 negative list: not a nonqualified commercial annuity (own-funds annuity contract from an insurance company/financial institution — see pensionDistributionIsNonqualifiedAnnuityNii, REQUIRED alongside this field when the pension is positive), not a QDRO nonemployee-spouse distribution, not a SECURE 2.0 Roth employer contribution, and NOT a government-employer pension including U.S. military retired pay (that belongs on line 26 instead, uncapped — routing it here caps the exclusion at $20,000 and over-taxes the filer; the engine cannot detect this misclassification from the boolean alone). NY excludes min($20,000, line 5b). Mutually exclusive with nyPensionIsGovernmentPension (both → decline); in this attestation, line 5b means all of pensionDistributionTaxable, IRA distributions included; on a joint return, part (a) must hold for each spouse who received any part of pensionDistributionTaxable. |
| nyPrivatePensionIsEntirelyRecipientsOwnNotInheritedAffirmedboolean | NY only — §6694 affirmation, REQUIRED (explicitly true or false) whenever nyPrivatePensionQualifiesFor20kExclusion:true is claimed on a positive pension.NY only — §6694 affirmation, REQUIRED (explicitly true or false) whenever nyPrivatePensionQualifiesFor20kExclusion:true is claimed on a positive pension. true = the ENTIRE line-5b amount is the recipient's OWN pension, no portion inherited from a decedent. IT-201-I (2025), p.11, line 29 'Beneficiaries': an inherited pension does NOT carry a fresh $20,000 exclusion for the beneficiary — it is the DECEDENT's own exclusion (qualified by the DECEDENT's age, not the recipient's), net of the decedent's own prior usage, allocated among all beneficiaries by inherited-value share. This engine does not model that allocation math, so false or omitted (when the exclusion is claimed) → decline rather than guess a fraction: absent → ny_private_pension_beneficiary_classification_needed, false → ny_private_pension_beneficiary_allocation_unsupported. Scoped to line 29 only — line 26 (government pension, full/uncapped) is unaffected; its own IT-201-I instruction already extends the exclusion to a beneficiary with no allocation or decedent-age test; in this attestation, line 5b means all of pensionDistributionTaxable, IRA distributions included. |
| nyNqdcPensionWagesAmountnumber | NY only — the NQDC-attributable portion of `wages` (a caller-asserted SUBSET, fed-pension-5b-ny-nqdc-pension-exclusion, 2026-09-02).NY only — the NQDC-attributable portion of `wages` (a caller-asserted SUBSET, fed-pension-5b-ny-nqdc-pension-exclusion, 2026-09-02). §457(f)/§409A nonqualified deferred compensation can never legitimately occupy pensionDistributionTaxable — it is a Form W-2 item (never Form 1099-R) that this engine correctly leaves in `wages`/`medicareWages` — but NY Tax Law §612(c)(3-a) and NY DTF Advisory Opinion TSB-A-10(1)I treat a qualifying periodic NQDC distribution as pension income eligible for the SAME $20,000 line-29 exclusion as an ordinary private pension. REQUIRES nyNqdcPensionQualifiesFor20kExclusionAffirmed:true. Must not exceed `wages` (decline otherwise). SHARES the $20,000 cap with any nyPrivatePensionQualifiesFor20kExclusion-eligible amount on the same return — additive independent caps would double the ceiling and under-tax. |
| nyNqdcPensionQualifiesFor20kExclusionAffirmedtrue | NY only — §6694 affirmation, REQUIRED whenever nyNqdcPensionWagesAmount is positive.NY only — §6694 affirmation, REQUIRED whenever nyNqdcPensionWagesAmount is positive. Attests the recipient reached age 59½ before January 1, 2025; the asserted amount is PERIODIC payments (not a lump sum) for services performed before retirement; and the plan is NONGOVERNMENTAL (a governmental §457(b) NQDC amount belongs on line 29 via nyPrivatePensionQualifiesFor20kExclusion instead — NOT line 26; IT-201-I explicitly excludes IRC §457 government deferred-comp from the line-26 government-pension exclusion). Absent/false → decline (ny_nqdc_pension_exclusion_unsupported). Supplied true without a positive nyNqdcPensionWagesAmount → decline (orphan affirmation). |
| scheduleCIncomenumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.scheduleCIncome. |
| scheduleCIsSingleSolePropFinalNetAffirmedtrue | Same as FederalProfile.scheduleCIsSingleSolePropFinalNetAffirmed. |
| scheduleCNoAmtAdjustmentAffirmedtrue | Same as FederalProfile.scheduleCNoAmtAdjustmentAffirmed. |
| socialSecurityWagesnumber | Same as FederalProfile.socialSecurityWages. |
| nyScheduleCNoStateBusinessAdjustmentsAffirmedtrue | NY only — §6694 affirmation REQUIRED with a Schedule C net on the NY return.NY only — §6694 affirmation REQUIRED with a Schedule C net on the NY return. Attests the federal Schedule C net has ZERO New York business-income adjustments (Form IT-225): no §168(k) bonus-depreciation difference (NY decouples — addition A-209 / Form IT-398), no 2025 research-&-experimental decoupling (Notice N-26-1, tax years beginning on/after 1/1/2025), no §179-SUV or other §179 difference, no other IT-225 A-series business-income modification. NY starts from federal AGI, so a NY addition the engine cannot see would under-tax; absent/false → NY declines (ny_schedule_c_adjustment_needs_review). NY needs NO worker-classification affirmation (no AB5/§164(f) disallowance). Separate NY MCTMT + NYC-UBT are surfaced as a VERIFY flag, not computed. |
| scheduleEIncomenumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. NY only — CA rejects this key outright (unrecognized_keys, HTTP 400); CA models no Schedule E. The FINAL federal Schedule E rental net, of ANY sign including exactly $0. Declaring it is what makes a Schedule-E state request buildable: it is the TRIGGERING FACT for scheduleERentalNoAmtDifferenceAffirmed, and supplying that affirmation without this field is a contradictory orphan that DECLINES (`federal_declined`, reason "supplied without a triggering fact"). Requires scheduleERentalIsPassiveFinalNet, scheduleERentalNotSection162Business and scheduleERentalNoAmtDifferenceAffirmed, plus nyScheduleENoStateBusinessAdjustmentsAffirmed on NY. |
| scheduleERentalIsPassiveFinalNettrue | NY only — CA rejects this key outright.NY only — CA rejects this key outright. §6694 affirmation REQUIRED with scheduleEIncome: attests the supplied figure is the FINAL net of a PASSIVE rental activity, after every §469 limitation the caller is responsible for applying. Absent → decline. |
| scheduleERentalNotSection162Businesstrue | NY only — CA rejects this key outright.NY only — CA rejects this key outright. §6694 affirmation REQUIRED with scheduleEIncome: attests the rental is NOT a §162 trade or business (which would carry self-employment tax this engine does not compute on the Schedule E path). Absent → decline. |
| scheduleERentalNoAmtDifferenceAffirmedtrue | NY only — CA rejects this key outright (unrecognized_keys, HTTP 400), because CA models no Schedule E.NY only — CA rejects this key outright (unrecognized_keys, HTTP 400), because CA models no Schedule E. §6694 federal AMT-parity affirmation, REQUIRED on the NY state endpoint whenever scheduleEIncome is present at ANY value, because NY re-runs the FEDERAL pipeline and that pipeline requires this attestation across the whole domain of the field. (In practice NY declines a rental LOSS on its own state grounds before the federal §469(i) route is reached, so the negative case is unreachable via /state today — stated as the federal contract it mirrors, not as a NY compute path.) Form 6251 line 2m: 'Refigure your passive activity gains and losses for the AMT' — this attests the AMT and regular-tax amounts for the activity are identical, which the engine cannot verify. Listed here from 2026-09-08: it was mandatory federally from 2026-09-01 but absent from this schema, so a caller building exactly what this spec prescribed got federal_declined asking for a field the spec never named. |
| nyScheduleENoStateBusinessAdjustmentsAffirmedtrue | NY only — §6694 affirmation REQUIRED with a Schedule E rental net on the NY return.NY only — §6694 affirmation REQUIRED with a Schedule E rental net on the NY return. Attests the federal rental net has ZERO New York depreciation adjustments (Form IT-225 / IT-398): STRAIGHT-LINE real-property depreciation (27.5-yr residential / 39-yr commercial), no §168(k) bonus, no cost-segregation 5/7/15-yr or QIP bonus component, no §179. NY conforms to the federal §469 passive rules (no separate NY PAL adjustment). A cost-seg/bonus component would be a NY addition the engine cannot see → under-tax; absent/false → NY declines (ny_schedule_e_adjustment_needs_review). Also requires the THREE federal affirmations scheduleERentalIsPassiveFinalNet + scheduleERentalNotSection162Business + scheduleERentalNoAmtDifferenceAffirmed (the Form 6251 line-2m AMT-parity attestation for a passive activity). |
curl https://tax-mcp.com/api/mcp/tax-compute/state \
-H "Authorization: Bearer $TAX_MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"state": "ny",
"year": 2025,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 80000,
"medicareWages": 80000,
"nyWageAdditions": 0,
"nycResident": true
}'{
"computed": true,
"state": "ny",
"year": 2025,
"filingStatus": "single",
"stateAGI": 80000,
"stateDeductions": 8000,
"stateTaxableIncome": 72000,
"stateTax": 3796,
"nycResidentTax": 2666,
"totalTax": 6462,
"lines": [
{
"lineId": "IT-201:19",
"label": "Federal AGI (NY rolling-conformity starting base)",
"amount": 80000,
"agiRole": "agi_base"
},
{
"lineId": "IT-201:33",
"label": "NY adjusted gross income (federal AGI + NY wage add-backs − NY subtractions)",
"amount": 80000,
"agiRole": "agi_total"
},
{
"lineId": "IT-201:34",
"label": "NY standard deduction",
"amount": 8000,
"agiRole": "below_agi",
"cite": "<primary-source cite — see full response>"
},
{
"lineId": "IT-201:36",
"label": "NY dependent exemptions (0 × $1,000)",
"amount": 0,
"agiRole": "below_agi"
},
{
"lineId": "IT-201:38",
"label": "NY taxable income",
"amount": 72000,
"agiRole": "below_agi"
},
{
"lineId": "IT-201:39",
"label": "NY State tax (rate schedule)",
"amount": 3796,
"agiRole": "below_agi",
"cite": "<primary-source cite — see full response>"
},
{
"lineId": "IT-201:47a",
"label": "NYC resident tax (rate schedule)",
"amount": 2666,
"agiRole": "below_agi",
"cite": "<primary-source cite — see full response>"
},
{
"lineId": "IT-201:46+58",
"label": "Total NY + NYC tax",
"amount": 6462,
"agiRole": "below_agi"
}
],
"flags": [
"NY-AGI assumes the supplied nyWageAdditions=$0 captures ALL NY wage add-backs (414(h) + IRC-125, W-2 box 14). A NY public-sector employee must include box-14 amounts here.",
"NY conformity assumed equal to federal AGI for income (wages-only; no NY subtractions modeled — pension/IRA exclusion, US-Treasury interest, 529, etc. require detail not present and would need their own decline-gate).",
"NY-AMT / NYC-UBT and other special regimes not computed (out of scope for this resident return)."
],
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "ny", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "<computation-support notice — see full response>"
}
}Full response, including line derivations
{
"computed": true,
"state": "ny",
"year": 2025,
"filingStatus": "single",
"stateAGI": 80000,
"stateDeductions": 8000,
"stateTaxableIncome": 72000,
"stateTax": 3796,
"nycResidentTax": 2666,
"totalTax": 6462,
"lines": [
{
"lineId": "IT-201:19",
"label": "Federal AGI (NY rolling-conformity starting base)",
"amount": 80000,
"agiRole": "agi_base"
},
{
"lineId": "IT-201:33",
"label": "NY adjusted gross income (federal AGI + NY wage add-backs − NY subtractions)",
"amount": 80000,
"agiRole": "agi_total"
},
{
"lineId": "IT-201:34",
"label": "NY standard deduction",
"amount": 8000,
"agiRole": "below_agi",
"cite": {
"jurisdiction": "ny",
"cellKey": "std_deduction.2025.single",
"authority": "NY DTF 2025 IT-201-I standard deduction (non-dependent filer) — Tax Law §614"
}
},
{
"lineId": "IT-201:36",
"label": "NY dependent exemptions (0 × $1,000)",
"amount": 0,
"agiRole": "below_agi"
},
{
"lineId": "IT-201:38",
"label": "NY taxable income",
"amount": 72000,
"agiRole": "below_agi"
},
{
"lineId": "IT-201:39",
"label": "NY State tax (rate schedule)",
"amount": 3796,
"agiRole": "below_agi",
"cite": {
"jurisdiction": "ny",
"cellKey": "brackets.2025.single",
"authority": "NY DTF 2025 IT-201-I New York State tax rate schedule — Tax Law §601"
}
},
{
"lineId": "IT-201:47a",
"label": "NYC resident tax (rate schedule)",
"amount": 2666,
"agiRole": "below_agi",
"cite": {
"jurisdiction": "nyc",
"cellKey": "brackets.2025.single",
"authority": "NY DTF 2025 IT-201-I New York City resident tax rate schedule — NYC Admin. Code §11-1701"
}
},
{
"lineId": "IT-201:46+58",
"label": "Total NY + NYC tax",
"amount": 6462,
"agiRole": "below_agi"
}
],
"flags": [
"NY-AGI assumes the supplied nyWageAdditions=$0 captures ALL NY wage add-backs (414(h) + IRC-125, W-2 box 14). A NY public-sector employee must include box-14 amounts here.",
"NY conformity assumed equal to federal AGI for income (wages-only; no NY subtractions modeled — pension/IRA exclusion, US-Treasury interest, 529, etc. require detail not present and would need their own decline-gate).",
"NY-AMT / NYC-UBT and other special regimes not computed (out of scope for this resident return)."
],
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "ny", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}
}Request body: Illinois
"state": "il". 62 fields.
| Field | Description |
|---|---|
| yearintegerrequired | Tax year; a year the state engine does not model declines. |
| filingStatus"single" | "married_filing_jointly" | "married_filing_separately" | "head_of_household"required | REQUIRED. The state endpoint re-runs the FEDERAL pipeline to derive its starting point, so it needs the same filing status the federal endpoint does. |
| wagesnumber | Same as FederalProfile.wages. |
| medicareWagesnumber | Medicare wages (W-2 box 5). CONDITIONALLY REQUIRED, and the condition cannot be expressed in this schema's `required` array, which is why it is spelled out here. This endpoint re-runs the FEDERAL…Medicare wages (W-2 box 5). CONDITIONALLY REQUIRED, and the condition cannot be expressed in this schema's `required` array, which is why it is spelled out here. This endpoint re-runs the FEDERAL pipeline, and that pipeline declines its Additional Medicare Tax determination whenever box 5 is omitted AND at least one of the federal pipeline's W-2 evidence fields is POSITIVE (the trigger is a positive amount, not mere presence: an explicit 0 does not arm it). Those fields are `wages`, `federalWithholding`, `medicareTaxWithheld` and `socialSecurityWages`, and this endpoint accepts all four, so a positive value in any of them arms it. WHAT A STATE CALLER ACTUALLY RECEIVES: `computed:false` with code `federal_declined` - NOT the federal-side code `surtax_additional_medicare`, which this endpoint does not surface; the box-5 explanation arrives in `reason`. Rationale: box 5 can exceed box 1 by an unbounded amount for real filers - 401(k)/403(b)/457(b) elective deferrals reduce box 1 while remaining subject to Medicare tax - so no finite margin can rule out the Additional Medicare Tax threshold being crossed at box 5. It is NOT required in the absence of positive W-2 evidence: a dividends-only or zero-wage return computes without it. Declared because a caller building exactly what this schema prescribes must be able to learn this requirement from the schema itself. |
| federalWithholdingnumber | Same as FederalProfile.federalWithholding. |
| medicareTaxWithheldnumber | Same as FederalProfile.medicareTaxWithheld. |
| taxableInterestnumber | CA/NY: requires stateIncomeConformsToFederal:true (else non-wage income declines); IL, NC and MI take it without. |
| ordinaryDividendsnumber | CA/NY: requires stateIncomeConformsToFederal:true. |
| qualifiedDividendsnumber | ≤ ordinaryDividends; CA/NY/IL/NC/MI tax it as ordinary (no preferential rate); CA/NY require stateIncomeConformsToFederal:true. |
| reit199ADividendsnumber | Same as FederalProfile.reit199ADividends. |
| netShortTermCapGainnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Taxed as ordinary by CA/NY/IL/NC/MI; CA/NY require stateIncomeConformsToFederal:true. |
| netLongTermCapGainnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Taxed as ordinary by CA/NY/IL/NC/MI; CA/NY require stateIncomeConformsToFederal:true. |
| priorYearCapLossCarryoverSTnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year SHORT-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Applied with the §1211(b) −$3,000 (−$1,500 MFS) annual limit. THIS ENDPOINT DOES NOT RETURN AN ENDING CARRYOVER: endingCapLossCarryoverST is a FEDERAL-response field and the state response has no equivalent, so track the remaining carryover yourself or read it from /federal. This field is the PRIOR-YEAR carryover only — do NOT also net it into netShortTermCapGain/netLongTermCapGain, which are CURRENT-YEAR nets before any carryover; doing both applies it twice (an executed $12,120 under-tax). Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. Accepted on the STATE endpoint for the same reason: this endpoint re-runs the federal pipeline, so this field's presence arms the identical Schedule-D-presence affirmation gates described above, and a caller who omits a zero-net carryover here bypasses them exactly as on /federal. If only an AMT-side carryover exists, send 0 (the return declines). |
| priorYearCapLossCarryoverLTnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year LONG-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Nets against long-term gain. THIS ENDPOINT DOES NOT RETURN AN ENDING CARRYOVER: endingCapLossCarryoverLT is a FEDERAL-response field and the state response has no equivalent, so track the remaining carryover yourself or read it from /federal. Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. Accepted on the STATE endpoint for the same reason: this endpoint re-runs the federal pipeline, so this field's presence arms the identical Schedule-D-presence affirmation gates described above, and a caller who omits a zero-net carryover here bypasses them exactly as on /federal. If only an AMT-side carryover exists, send 0 (the return declines). |
| capLossCarryoverNoAmtDifferenceAffirmedtrue | §6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the trigger is PRESENCE, not magnitude, and not the carryover field specifically.§6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the trigger is PRESENCE, not magnitude, and not the carryover field specifically. WHAT `true` ATTESTS (identical to FederalProfile.capLossCarryoverNoAmtDifferenceAffirmed): EITHER (a) this return has no prior-year capital-loss carryover at all, for regular tax or AMT — the common case, and attesting true is how you say so — OR (b) a carryover exists and its ENTERING AMT-SIDE amount equals its regular-tax amount. It covers a carryover HOWEVER it reached this engine, including one the caller already netted into netShortTermCapGain/netLongTermCapGain, and it additionally attests the carryover was NOT supplied BOTH ways (netted into a scalar AND as priorYearCapLossCarryover*), which would apply it twice. DO NOT SUPPLY IT DEFENSIVELY: on a return carrying NO Schedule D input at all this is a contradictory orphan affirmation and the return is DECLINED - a state caller receives `computed:false` with code `federal_declined`, the orphan explanation in `reason`. An AMT-only carryover is NOT covered: send priorYearCapLossCarryoverST/LT as 0, and the return declines. |
| mortgageInterestnumber | Same as FederalProfile.mortgageInterest. |
| mortgageAvgBalancenumber | Same as FederalProfile.mortgageAvgBalance. |
| mortgageInterestExcludesExcessRefinancingProceedsboolean | Same as FederalProfile.mortgageInterestExcludesExcessRefinancingProceeds. |
| mortgageInterestSecuresAmtQualifiedDwellingboolean | Same as FederalProfile.mortgageInterestSecuresAmtQualifiedDwelling. |
| mortgageInterestSecuresSec121PrincipalResidenceboolean | Same as FederalProfile.mortgageInterestSecuresSec121PrincipalResidence. |
| foreignTaxPaidnumber | Same as FederalProfile.foreignTaxPaid. |
| foreignIncomeAllPassive1099true | Same as FederalProfile.foreignIncomeAllPassive1099: all foreign income is passive and shown on a qualified payee statement (§6724(d)(2)), which is broader than the 1099 family. |
| foreignTaxIsFullyCreditableAffirmedtrue | Same as FederalProfile.foreignTaxIsFullyCreditableAffirmed. |
| foreignSourceGrossIncomenumber | Same as FederalProfile.foreignSourceGrossIncome. |
| foreignQualifiedDividendsAndCapGainsnumber | Same as FederalProfile.foreignQualifiedDividendsAndCapGains. |
| foreignTaxNoCarryoverAffirmedtrue | Same as FederalProfile.foreignTaxNoCarryoverAffirmed. |
| foreignSourceNoForm1116PartILines2Through5EntryAffirmedtrue | Same as FederalProfile.foreignSourceNoForm1116PartILines2Through5EntryAffirmed. |
| foreignSourceNoForm1116Line16AdjustmentAffirmedtrue | Same as FederalProfile.foreignSourceNoForm1116Line16AdjustmentAffirmed. |
| foreignTaxNoForm1116Line12ReductionAffirmedtrue | Same as FederalProfile.foreignTaxNoForm1116Line12ReductionAffirmed. |
| stateLocalIncomeTaxnumber | Same as FederalProfile.stateLocalIncomeTax. |
| realEstateTaxnumber | Same as FederalProfile.realEstateTax. |
| sec1250UnrecapturedGainnumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.sec1250UnrecapturedGain. |
| collectibles28Gainnumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.collectibles28Gain. |
| specialRateGainNoAmtScheduleDDifferenceAffirmedboolean | Same as FederalProfile.specialRateGainNoAmtScheduleDDifferenceAffirmed. |
| collectibles28NoSec1202ExclusionPreferenceAffirmedtrue | §6694 affirmation REQUIRED on the same Schedule-D-presence trigger.§6694 affirmation REQUIRED on the same Schedule-D-presence trigger. WHAT `true` ATTESTS (identical to FederalProfile.collectibles28NoSec1202ExclusionPreferenceAffirmed): EITHER no §1202 qualified-small-business-stock exclusion is involved on this return at all, OR every §1202 exclusion claimed arises solely from stock acquired AFTER 2010-09-27 and so carries no §57(a)(7) AMT preference. This engine hardcodes AMT other-preferences to $0, so an unattested pre-2010-09-28 exclusion would UNDER-state AMT — and the preference is 7% of the EXCLUDED gain, which no input here carries and which netting cannot reduce, so it survives even when every capital-gain figure on the return nets to $0. That is why the trigger is presence of Schedule D activity rather than a positive amount. DO NOT SUPPLY IT DEFENSIVELY: on a return carrying NO Schedule D input at all this is a contradictory orphan affirmation and the return is DECLINED - a state caller receives `computed:false` with code `federal_declined`, the orphan explanation in `reason`. |
| qbiDeductionnumber | Same as FederalProfile.qbiDeduction; on /state the decline arrives as federal_declined. |
| pensionDistributionTaxablenumber | State (CA, NY, IL, NC, MI) — the fully-taxable federal line-4b/5b pension/IRA distribution (with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true).State (CA, NY, IL, NC, MI) — the fully-taxable federal line-4b/5b pension/IRA distribution (with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true). IL subtracts it with ilPensionIsQualifiedRetirementIncomeAffirmed; NC taxes it (its retirement deductions are not modeled, an over-tax); MI: see miNoRetirementOrAgeDeductionsAffirmed and miRetirementFactsAffirmed. NY EXCLUDES it: supply nyPensionIsGovernmentPension (IT-201 line 26, full) OR nyPrivatePensionQualifiesFor20kExclusion (IT-201 line 29, min($20k,5b)); neither → the pension stays NY-taxable. CA CONFORMS and TAXES it by default, with ONE modeled exclusion: caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true excludes min($20,000, line 5b), AGI-gated (R&TC §§17132.9/17132.10) — and a VERIFY flag names the unmodeled CA divergences enumerated in CA_COMPUTE_CAPABILITY.state_adjustments.pension (served on GET /api/mcp/tax-compute/state), which is the single authoritative list — this text states no count of its own, because a count restated in many places is a claim that must be maintained in many places, and on this surface it was not. (1) Tier-2 railroad retirement (RRB-1099-R), which CA EXCLUDES (45 U.S.C. §231m) — omitting it OVER-taxes. (2) CA's early-distribution additional tax, which this engine computes for NEITHER jurisdiction: 2.5% (R&TC §17085(c)(1)), raised to 6% where §72(t)(6) applies (§17085(c)(2), FTB 3805P line 4), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax — omitting THIS one UNDER-taxes. (3) An IRA-to-HSA one-time funding distribution under §408(d)(9), EXCLUDED from federal gross income under §408(d)(9)(A) but which California conforms out entirely (R&TC §17215.4) — the FTB 3805P instructions require it ADDED BACK to CA AGI, and — where the distribution is premature under the §72(t) rules — a 2 1/2% additional tax, which can be owed even where no federal §72(t) tax is. This one runs the OPPOSITE way from (1): omitting it UNDER-taxes California, and the engine has no field for it, so a CA return carrying one is outside the modeled surface. |
| pensionDistributionFullyTaxableAffirmedtrue | §6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint, one of TWO required affirmations):§6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint, one of TWO required affirmations): the fully-taxable 1099-R box 2a distribution, no basis/QCD/rollover/Roth/NUA. |
| pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmedtrue | §6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed (same contract as the federal endpoint).§6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed (same contract as the federal endpoint). THIS SCHEMA DELIBERATELY DOES NOT RESTATE THE RULE — see the federal endpoint's field of this name for the operative condition, which GOVERNS. (fed-pension-5b-72q-levy-exception-fix, 2026-08-29 — see the federal endpoint's pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmed field, required on the SAME contract here whenever this field is true and pensionDistributionIsNonqualifiedAnnuityNii is not explicitly false; and pensionDistributionNoSeppModificationRecaptureAffirmed, required on the SAME contract here whenever this field is true — regardless of which specific basis — per fed-pension-5b-sepp-modification-recapture-gate, 2026-08-29). SIMPLE-IRA timing within the §72(t)(6)(A) 2-year period does not by itself disqualify a 59½+ or exception-covered distribution — it only affects the RATE of a genuinely early, no-exception distribution, which this engine does not compute. CALIFORNIA DIVERGES on that rate and this engine computes it for neither jurisdiction: CA's analogue is 2.5% (R&TC §17085(c)(1)), 6% where §72(t)(6) applies (§17085(c)(2)), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax. THE 2-YEAR CLOCK IS ANCHORED TO PARTICIPATION IN THE EMPLOYER'S PLAN, NOT THE ACCOUNT'S AGE: §72(t)(6)(A) runs the period from 'the date such individual first participated in any qualified salary reduction arrangement maintained by the individual's employer under section 408(p)(2)', and IRS Notice 98-4 Q&A I-5 gives the operational start — 'the first day on which contributions made by the individual's employer are deposited in the individual's SIMPLE IRA' (the Form 5329 instructions and FTB 3805P agree). It is measured PER EMPLOYER, so a new employer's SIMPLE starts a NEW 2-year period for that employer's own contributions — reading the clock as the ACCOUNT's age can UNDER-tax at 10%/2.5%. A transfer or rollover between SIMPLE IRAs under the SAME employer's arrangement does not restart it. ACROSS EMPLOYERS THE PERIOD FOLLOWS EACH EMPLOYER'S OWN CONTRIBUTIONS — 26 CFR §1.408A-4 A-4(b): 'This 2-year period of section 408(d)(3)(G) applies separately to the contributions of each of an individual's employers maintaining a SIMPLE IRA Plan' — and A-4(b) itself identifies that period as 'the 2-year period described in section 72(t)(6)', so it is THIS period, not a rollover-only clock. The rule it construes is §408(d)(3)(G)'s restriction on conversions; applying the same contribution-tracing to the RATE is this engine's reading of it. It runs BOTH ways. Dollars traceable to a prior employer whose period has EXPIRED keep that expiry and are NOT pulled into the new employer's open window. Dollars traceable to a prior employer whose period is STILL OPEN carry it into the new account and stay at 25%/6% even after the receiving employer's own window closes — until that prior period itself expires, not indefinitely. Where provenance cannot be substantiated, treat the amount as still inside a 2-year period (25%/6% — federal and CA respectively; NY has no analogous additional tax) rather than assuming the lower rate. |
| pensionDistributionIsNonqualifiedAnnuityNiiboolean | NOT the same contract as the federal endpoint — on /state this field is REQUIRED (else ny_private_pension_exclusion_classification_needed decline) whenever…NOT the same contract as the federal endpoint — on /state this field is REQUIRED (else ny_private_pension_exclusion_classification_needed decline) whenever nyPrivatePensionQualifiesFor20kExclusion:true is claimed on a positive pension, UNCONDITIONALLY, regardless of whether federal §1411 NIIT materiality would independently require it — NY IT-201-I's own negative list for the line-29 $20,000 exclusion excludes a nonqualified commercial annuity, a fact the federal-only materiality gate can leave unaffirmed below the NIIT threshold. true (a nonqualified commercial annuity) is also flatly inconsistent with nyPensionIsGovernmentPension:true or nyPrivatePensionQualifiesFor20kExclusion:true → decline (pension_exclusion_classification_ambiguous), and with CA's caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true → decline (ca_pension_exclusion_classification_ambiguous). IL: must be false to use ilPensionIsQualifiedRetirementIncomeAffirmed (else il_needs_review). |
| pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmedboolean | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true AND pensionDistributionIsNonqualifiedAnnuityNii is NOT explicitly false — see the federal endpoint's own field description for the full §72(q)(2) accept-list citation. |
| pensionDistributionEarlyWithdrawalBasisIsAvailableForThisPlanTypeAffirmedboolean | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — see the federal endpoint's own field description for the full plan-type-divergence citation. |
| pensionDistributionNoSeppModificationRecaptureAffirmedtrue | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — see the federal endpoint's own field description for the full SEPP-modification-recapture citation. |
| socialSecurityBenefitsnumber | Social Security benefits (SSA-1099 box 5, box 3 less box 4).Social Security benefits (SSA-1099 box 5, box 3 less box 4). CA, NY, IL, NC and MI FULLY EXCLUDE taxable Social Security: the engine recomputes the federal §86 taxable portion (line 6b) in-process and SUBTRACTS it on Schedule CA (540) line 6 col B (CA) / IT-201 line 27 (NY) / IL-1040 line 5 / D-400 line 9 / MI-1040 line 13. REQUIRES socialSecurityStandardCaseAffirmed:true (and socialSecurityMfsLivedWithSpouse for MFS) — the SAME §86 gates as the federal endpoint; an unaffirmed SS return declines federally → declines the state. |
| taxExemptInterestnumber | Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand.Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand. IL, NC and MI: REQUIRED (0 if none), added in full (IL-1040 line 2, D-400 line 7, MI-1040 line 11). CA/NY: accepted so the federal §86 recompute is correct, BUT any positive amount DECLINES the state return (state_tax_exempt_interest_unsupported): the CA out-of-state-muni add-back (Schedule CA line 2 col C) / NY non-NY-muni add-back (IT-225 A-101) is not sized in this slice. |
| socialSecurityStandardCaseAffirmedtrue | §6694 affirmation REQUIRED when socialSecurityBenefits is supplied:§6694 affirmation REQUIRED when socialSecurityBenefits is supplied: attests the standard §86 worksheet applies (no lump-sum election, no Form 8815, §137, §85(c), foreign-earned-income or §931-933 add-backs, no Roth-conversion or other provisional-income complications the engine does not model). Absent → declines (fail-closed). |
| socialSecurityMfsLivedWithSpouseboolean | REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately:REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately: whether the taxpayer lived with their spouse at any time during the year (§86(c)(1)(C) sets the MFS base amount to $0 if true). Absent for MFS+SS → declines. |
| noForeignOrTerritoryExclusionAffirmedbooleanrequired | Same as FederalProfile.noForeignOrTerritoryExclusionAffirmed; false declines a CA, NY, IL, NC or MI return (as federal_declined). |
| taxExemptInterestNoPrivateActivityBondstrue | §6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g).§6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g). Required with a positive taxExemptInterest on IL, NC and MI; on CA/NY a positive amount declines regardless. |
| estateTrustK1NoAmtAdjustmentAffirmedtrue | §6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest.§6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest. WHAT `true` ATTESTS: no Schedule K-1 (Form 1041) received for this tax year, from any estate or trust, shows a positive amount in box 12 code A (adjustment for minimum tax purposes, Form 6251 line 2j) or any amount, positive or negative, in box 12 codes B through I. Attest true if no such K-1 was received, or if every code A amount is zero or negative and codes B through I are blank on all of them (a negative code A left out over-states the tax). The engine sets line 2j to $0. Absent or false with any of those inputs: the return declines (estate_trust_amt_adjustment_unmodeled); true with none of them: declined as an orphan; false always declines (a preparer completes Form 6251). Never default it. Not detected: a K-1 with a code A or B-I amount but no income boxes, on a return with none of those inputs. |
| otherIncomePresentButUnmodeledarray of string | Same as FederalProfile.otherIncomePresentButUnmodeled; on /state the decline arrives as federal_declined. |
| stateenum (14 values)required | ca, ny, il, nc, mi, or a no-income-tax state ($0 or a decline). Any other state is rejected. |
| residency"full_year_resident" | "part_year_resident" | "part_year" | "nonresident" | "non_resident" | Residency for the year; only a full-year resident computes, part-year and nonresident decline. |
| canBeClaimedAsDependentbooleanrequired | Required. true when another taxpayer can claim this filer (on a joint return, either spouse) as a dependent; CA, NY and IL decline true (dependent_filer_needs_review); NC and MI compute a single or…Required. true when another taxpayer can claim this filer (on a joint return, either spouse) as a dependent; CA, NY and IL decline true (dependent_filer_needs_review); NC and MI compute a single or married_filing_separately dependent filer who claims no dependents (NC full standard deduction; MI $1,500), and a no-income-tax state's $0 is unchanged. |
| ilNoAdditionsOrRecaptureAffirmedboolean | IL only, required true (else the IL return declines):IL only, required true (else the IL return declines): IL-1040 line 3 (other additions, Schedule M) is $0 for this year — including a child's Form 8814 tax-exempt income, partnership, S corporation, estate or trust distributive-share additions, Lloyd's losses, non-Illinois §529 or ABLE earnings excluded from federal AGI, Illinois §529 or ABLE deduction recapture, IL-4562 depreciation, gain excluded under §1202 (from 2026), the pass-through entity tax add-back, and every other addition — and there is no recapture of investment credits (line 13, Schedule 4255). |
| ilFilingStatusMatchesFederalAffirmedboolean | IL only, required true (else declines):IL only, required true (else declines): the Illinois filing status is the federal filing status, and on a joint return both spouses were full-year Illinois residents (no Illinois married-filing-separately return split from a federal joint return). |
| ilPensionIsQualifiedRetirementIncomeAffirmedboolean | IL only, optional: subtracts the federal pension line (IL-1040 line 5); requires pensionDistributionIsNonqualifiedAnnuityNii:false. Attests: the entire pensionDistributionTaxable amount is…IL only, optional: subtracts the federal pension line (IL-1040 line 5); requires pensionDistributionIsNonqualifiedAnnuityNii:false. Attests: the entire pensionDistributionTaxable amount is Illinois-qualified retirement income (35 ILCS 5/203(a)(2)(F), (L), (W): an amount included under IRC §402(a), 402(c), 403(a), 403(b), 406(a), 407(a) or 408 or from a retirement or disability plan for employees of any governmental agency or unit, including 401(k) and other qualified-plan distributions, IRAs, Roth conversions, SEPs, governmental §457(b) plans and railroad retirement); it does NOT include a nongovernmental §457(b) plan, a commercial annuity, a non-government disability plan, or retired-partner payments. Without it the pension stays taxable (over-tax). |
| ilDependentsClaimedinteger | IL only: people claimed as dependents on the federal return (any age), each adding one exemption allowance. |
| ilFilerAge65OrOlderboolean | IL only: adds $1,000 to the exemption. |
| ilFilerBlindboolean | IL only: adds $1,000 to the exemption. |
| ilSpouseAge65OrOlderboolean | IL only, married_filing_jointly only (else 400): adds $1,000. |
| ilSpouseBlindboolean | IL only, married_filing_jointly only (else 400): adds $1,000. |
curl https://tax-mcp.com/api/mcp/tax-compute/state \
-H "Authorization: Bearer $TAX_MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"state": "il",
"year": 2025,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 60000,
"medicareWages": 60000,
"taxExemptInterest": 0,
"ilNoAdditionsOrRecaptureAffirmed": true,
"ilFilingStatusMatchesFederalAffirmed": true
}'{
"computed": true,
"state": "il",
"year": 2025,
"filingStatus": "single",
"federalAGI": 60000,
"baseIncome": 60000,
"exemption": 2850,
"netIncome": 57150,
"incomeTax": 2829,
"additionalTaxes": [],
"totalTax": 2829,
"notEvaluated": [
"credits (Schedule CR other-state tax, Schedule ICR property tax and K-12 education, Illinois EITC and child tax credit) — over-tax",
"Schedule M subtractions (e.g. U.S. Treasury interest) and line 5 amounts other than Social Security and attested retirement income — over-tax",
"a married non-joint filer's spouse exemptions (allowed by 35 ILCS 5/204(c) and (d) when the spouse has no gross income and is not another taxpayer's dependent) — over-tax",
"household employment tax, use tax and surcharges (IL-1040 lines 20-22) — under-tax when owed",
"line 1 is federal AGI; the same return rounded otherwise can show a different AGI (not_modeled.cents_rounding), or a different line 5 when the pension field combines IRA and pension amounts, moving the tax by up to 4.95% of the difference plus $1; within $100 of the exemption cliff the return declines, and a larger difference there can flip the whole exemption undetected",
"Illinois payments, refund and the filing requirement"
],
"attestationsRelied": [
"ilNoAdditionsOrRecaptureAffirmed",
"ilFilingStatusMatchesFederalAffirmed"
],
"lines": [
{ "lineId": "IL-1040:1", "label": "Federal adjusted gross income", "amount": 60000 },
{
"lineId": "IL-1040:2",
"label": "Federally tax-exempt interest and dividend income",
"amount": 0
},
{
"lineId": "IL-1040:5",
"label": "Social Security and qualified retirement income subtraction",
"amount": 0
},
{ "lineId": "IL-1040:9", "label": "Illinois base income", "amount": 60000 },
{ "lineId": "IL-1040:10", "label": "Exemption allowance", "amount": 2850 },
{ "lineId": "IL-1040:11", "label": "Net income", "amount": 57150 },
{ "lineId": "IL-1040:12", "label": "Income tax (4.95%)", "amount": 2829 }
],
"flags": [],
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "il", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "<computation-support notice — see full response>"
}
}Full response, including line derivations
{
"computed": true,
"state": "il",
"year": 2025,
"filingStatus": "single",
"federalAGI": 60000,
"baseIncome": 60000,
"exemption": 2850,
"netIncome": 57150,
"incomeTax": 2829,
"additionalTaxes": [],
"totalTax": 2829,
"notEvaluated": [
"credits (Schedule CR other-state tax, Schedule ICR property tax and K-12 education, Illinois EITC and child tax credit) — over-tax",
"Schedule M subtractions (e.g. U.S. Treasury interest) and line 5 amounts other than Social Security and attested retirement income — over-tax",
"a married non-joint filer's spouse exemptions (allowed by 35 ILCS 5/204(c) and (d) when the spouse has no gross income and is not another taxpayer's dependent) — over-tax",
"household employment tax, use tax and surcharges (IL-1040 lines 20-22) — under-tax when owed",
"line 1 is federal AGI; the same return rounded otherwise can show a different AGI (not_modeled.cents_rounding), or a different line 5 when the pension field combines IRA and pension amounts, moving the tax by up to 4.95% of the difference plus $1; within $100 of the exemption cliff the return declines, and a larger difference there can flip the whole exemption undetected",
"Illinois payments, refund and the filing requirement"
],
"attestationsRelied": [
"ilNoAdditionsOrRecaptureAffirmed",
"ilFilingStatusMatchesFederalAffirmed"
],
"lines": [
{ "lineId": "IL-1040:1", "label": "Federal adjusted gross income", "amount": 60000 },
{
"lineId": "IL-1040:2",
"label": "Federally tax-exempt interest and dividend income",
"amount": 0
},
{
"lineId": "IL-1040:5",
"label": "Social Security and qualified retirement income subtraction",
"amount": 0
},
{ "lineId": "IL-1040:9", "label": "Illinois base income", "amount": 60000 },
{ "lineId": "IL-1040:10", "label": "Exemption allowance", "amount": 2850 },
{ "lineId": "IL-1040:11", "label": "Net income", "amount": 57150 },
{ "lineId": "IL-1040:12", "label": "Income tax (4.95%)", "amount": 2829 }
],
"flags": [],
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "il", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}
}Request body: North Carolina
"state": "nc". 58 fields.
| Field | Description |
|---|---|
| yearintegerrequired | Tax year; a year the state engine does not model declines. |
| filingStatus"single" | "married_filing_jointly" | "married_filing_separately" | "head_of_household"required | REQUIRED. The state endpoint re-runs the FEDERAL pipeline to derive its starting point, so it needs the same filing status the federal endpoint does. |
| wagesnumber | Same as FederalProfile.wages. |
| medicareWagesnumber | Medicare wages (W-2 box 5). CONDITIONALLY REQUIRED, and the condition cannot be expressed in this schema's `required` array, which is why it is spelled out here. This endpoint re-runs the FEDERAL…Medicare wages (W-2 box 5). CONDITIONALLY REQUIRED, and the condition cannot be expressed in this schema's `required` array, which is why it is spelled out here. This endpoint re-runs the FEDERAL pipeline, and that pipeline declines its Additional Medicare Tax determination whenever box 5 is omitted AND at least one of the federal pipeline's W-2 evidence fields is POSITIVE (the trigger is a positive amount, not mere presence: an explicit 0 does not arm it). Those fields are `wages`, `federalWithholding`, `medicareTaxWithheld` and `socialSecurityWages`, and this endpoint accepts all four, so a positive value in any of them arms it. WHAT A STATE CALLER ACTUALLY RECEIVES: `computed:false` with code `federal_declined` - NOT the federal-side code `surtax_additional_medicare`, which this endpoint does not surface; the box-5 explanation arrives in `reason`. Rationale: box 5 can exceed box 1 by an unbounded amount for real filers - 401(k)/403(b)/457(b) elective deferrals reduce box 1 while remaining subject to Medicare tax - so no finite margin can rule out the Additional Medicare Tax threshold being crossed at box 5. It is NOT required in the absence of positive W-2 evidence: a dividends-only or zero-wage return computes without it. Declared because a caller building exactly what this schema prescribes must be able to learn this requirement from the schema itself. |
| federalWithholdingnumber | Same as FederalProfile.federalWithholding. |
| medicareTaxWithheldnumber | Same as FederalProfile.medicareTaxWithheld. |
| taxableInterestnumber | CA/NY: requires stateIncomeConformsToFederal:true (else non-wage income declines); IL, NC and MI take it without. |
| ordinaryDividendsnumber | CA/NY: requires stateIncomeConformsToFederal:true. |
| qualifiedDividendsnumber | ≤ ordinaryDividends; CA/NY/IL/NC/MI tax it as ordinary (no preferential rate); CA/NY require stateIncomeConformsToFederal:true. |
| reit199ADividendsnumber | Same as FederalProfile.reit199ADividends. |
| netShortTermCapGainnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Taxed as ordinary by CA/NY/IL/NC/MI; CA/NY require stateIncomeConformsToFederal:true. |
| netLongTermCapGainnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Taxed as ordinary by CA/NY/IL/NC/MI; CA/NY require stateIncomeConformsToFederal:true. |
| priorYearCapLossCarryoverSTnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year SHORT-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Applied with the §1211(b) −$3,000 (−$1,500 MFS) annual limit. THIS ENDPOINT DOES NOT RETURN AN ENDING CARRYOVER: endingCapLossCarryoverST is a FEDERAL-response field and the state response has no equivalent, so track the remaining carryover yourself or read it from /federal. This field is the PRIOR-YEAR carryover only — do NOT also net it into netShortTermCapGain/netLongTermCapGain, which are CURRENT-YEAR nets before any carryover; doing both applies it twice (an executed $12,120 under-tax). Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. Accepted on the STATE endpoint for the same reason: this endpoint re-runs the federal pipeline, so this field's presence arms the identical Schedule-D-presence affirmation gates described above, and a caller who omits a zero-net carryover here bypasses them exactly as on /federal. If only an AMT-side carryover exists, send 0 (the return declines). |
| priorYearCapLossCarryoverLTnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year LONG-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Nets against long-term gain. THIS ENDPOINT DOES NOT RETURN AN ENDING CARRYOVER: endingCapLossCarryoverLT is a FEDERAL-response field and the state response has no equivalent, so track the remaining carryover yourself or read it from /federal. Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. Accepted on the STATE endpoint for the same reason: this endpoint re-runs the federal pipeline, so this field's presence arms the identical Schedule-D-presence affirmation gates described above, and a caller who omits a zero-net carryover here bypasses them exactly as on /federal. If only an AMT-side carryover exists, send 0 (the return declines). |
| capLossCarryoverNoAmtDifferenceAffirmedtrue | §6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the trigger is PRESENCE, not magnitude, and not the carryover field specifically.§6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the trigger is PRESENCE, not magnitude, and not the carryover field specifically. WHAT `true` ATTESTS (identical to FederalProfile.capLossCarryoverNoAmtDifferenceAffirmed): EITHER (a) this return has no prior-year capital-loss carryover at all, for regular tax or AMT — the common case, and attesting true is how you say so — OR (b) a carryover exists and its ENTERING AMT-SIDE amount equals its regular-tax amount. It covers a carryover HOWEVER it reached this engine, including one the caller already netted into netShortTermCapGain/netLongTermCapGain, and it additionally attests the carryover was NOT supplied BOTH ways (netted into a scalar AND as priorYearCapLossCarryover*), which would apply it twice. DO NOT SUPPLY IT DEFENSIVELY: on a return carrying NO Schedule D input at all this is a contradictory orphan affirmation and the return is DECLINED - a state caller receives `computed:false` with code `federal_declined`, the orphan explanation in `reason`. An AMT-only carryover is NOT covered: send priorYearCapLossCarryoverST/LT as 0, and the return declines. |
| mortgageInterestnumber | Same as FederalProfile.mortgageInterest. |
| mortgageAvgBalancenumber | Same as FederalProfile.mortgageAvgBalance. |
| mortgageInterestExcludesExcessRefinancingProceedsboolean | Same as FederalProfile.mortgageInterestExcludesExcessRefinancingProceeds. |
| mortgageInterestSecuresAmtQualifiedDwellingboolean | Same as FederalProfile.mortgageInterestSecuresAmtQualifiedDwelling. |
| mortgageInterestSecuresSec121PrincipalResidenceboolean | Same as FederalProfile.mortgageInterestSecuresSec121PrincipalResidence. |
| foreignTaxPaidnumber | Same as FederalProfile.foreignTaxPaid. |
| foreignIncomeAllPassive1099true | Same as FederalProfile.foreignIncomeAllPassive1099: all foreign income is passive and shown on a qualified payee statement (§6724(d)(2)), which is broader than the 1099 family. |
| foreignTaxIsFullyCreditableAffirmedtrue | Same as FederalProfile.foreignTaxIsFullyCreditableAffirmed. |
| foreignSourceGrossIncomenumber | Same as FederalProfile.foreignSourceGrossIncome. |
| foreignQualifiedDividendsAndCapGainsnumber | Same as FederalProfile.foreignQualifiedDividendsAndCapGains. |
| foreignTaxNoCarryoverAffirmedtrue | Same as FederalProfile.foreignTaxNoCarryoverAffirmed. |
| foreignSourceNoForm1116PartILines2Through5EntryAffirmedtrue | Same as FederalProfile.foreignSourceNoForm1116PartILines2Through5EntryAffirmed. |
| foreignSourceNoForm1116Line16AdjustmentAffirmedtrue | Same as FederalProfile.foreignSourceNoForm1116Line16AdjustmentAffirmed. |
| foreignTaxNoForm1116Line12ReductionAffirmedtrue | Same as FederalProfile.foreignTaxNoForm1116Line12ReductionAffirmed. |
| stateLocalIncomeTaxnumber | Same as FederalProfile.stateLocalIncomeTax. |
| realEstateTaxnumber | Same as FederalProfile.realEstateTax. |
| sec1250UnrecapturedGainnumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.sec1250UnrecapturedGain. |
| collectibles28Gainnumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.collectibles28Gain. |
| specialRateGainNoAmtScheduleDDifferenceAffirmedboolean | Same as FederalProfile.specialRateGainNoAmtScheduleDDifferenceAffirmed. |
| collectibles28NoSec1202ExclusionPreferenceAffirmedtrue | §6694 affirmation REQUIRED on the same Schedule-D-presence trigger.§6694 affirmation REQUIRED on the same Schedule-D-presence trigger. WHAT `true` ATTESTS (identical to FederalProfile.collectibles28NoSec1202ExclusionPreferenceAffirmed): EITHER no §1202 qualified-small-business-stock exclusion is involved on this return at all, OR every §1202 exclusion claimed arises solely from stock acquired AFTER 2010-09-27 and so carries no §57(a)(7) AMT preference. This engine hardcodes AMT other-preferences to $0, so an unattested pre-2010-09-28 exclusion would UNDER-state AMT — and the preference is 7% of the EXCLUDED gain, which no input here carries and which netting cannot reduce, so it survives even when every capital-gain figure on the return nets to $0. That is why the trigger is presence of Schedule D activity rather than a positive amount. DO NOT SUPPLY IT DEFENSIVELY: on a return carrying NO Schedule D input at all this is a contradictory orphan affirmation and the return is DECLINED - a state caller receives `computed:false` with code `federal_declined`, the orphan explanation in `reason`. |
| qbiDeductionnumber | Same as FederalProfile.qbiDeduction; on /state the decline arrives as federal_declined. |
| pensionDistributionTaxablenumber | State (CA, NY, IL, NC, MI) — the fully-taxable federal line-4b/5b pension/IRA distribution (with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true).State (CA, NY, IL, NC, MI) — the fully-taxable federal line-4b/5b pension/IRA distribution (with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true). IL subtracts it with ilPensionIsQualifiedRetirementIncomeAffirmed; NC taxes it (its retirement deductions are not modeled, an over-tax); MI: see miNoRetirementOrAgeDeductionsAffirmed and miRetirementFactsAffirmed. NY EXCLUDES it: supply nyPensionIsGovernmentPension (IT-201 line 26, full) OR nyPrivatePensionQualifiesFor20kExclusion (IT-201 line 29, min($20k,5b)); neither → the pension stays NY-taxable. CA CONFORMS and TAXES it by default, with ONE modeled exclusion: caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true excludes min($20,000, line 5b), AGI-gated (R&TC §§17132.9/17132.10) — and a VERIFY flag names the unmodeled CA divergences enumerated in CA_COMPUTE_CAPABILITY.state_adjustments.pension (served on GET /api/mcp/tax-compute/state), which is the single authoritative list — this text states no count of its own, because a count restated in many places is a claim that must be maintained in many places, and on this surface it was not. (1) Tier-2 railroad retirement (RRB-1099-R), which CA EXCLUDES (45 U.S.C. §231m) — omitting it OVER-taxes. (2) CA's early-distribution additional tax, which this engine computes for NEITHER jurisdiction: 2.5% (R&TC §17085(c)(1)), raised to 6% where §72(t)(6) applies (§17085(c)(2), FTB 3805P line 4), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax — omitting THIS one UNDER-taxes. (3) An IRA-to-HSA one-time funding distribution under §408(d)(9), EXCLUDED from federal gross income under §408(d)(9)(A) but which California conforms out entirely (R&TC §17215.4) — the FTB 3805P instructions require it ADDED BACK to CA AGI, and — where the distribution is premature under the §72(t) rules — a 2 1/2% additional tax, which can be owed even where no federal §72(t) tax is. This one runs the OPPOSITE way from (1): omitting it UNDER-taxes California, and the engine has no field for it, so a CA return carrying one is outside the modeled surface. |
| pensionDistributionFullyTaxableAffirmedtrue | §6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint, one of TWO required affirmations):§6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint, one of TWO required affirmations): the fully-taxable 1099-R box 2a distribution, no basis/QCD/rollover/Roth/NUA. |
| pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmedtrue | §6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed (same contract as the federal endpoint).§6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed (same contract as the federal endpoint). THIS SCHEMA DELIBERATELY DOES NOT RESTATE THE RULE — see the federal endpoint's field of this name for the operative condition, which GOVERNS. (fed-pension-5b-72q-levy-exception-fix, 2026-08-29 — see the federal endpoint's pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmed field, required on the SAME contract here whenever this field is true and pensionDistributionIsNonqualifiedAnnuityNii is not explicitly false; and pensionDistributionNoSeppModificationRecaptureAffirmed, required on the SAME contract here whenever this field is true — regardless of which specific basis — per fed-pension-5b-sepp-modification-recapture-gate, 2026-08-29). SIMPLE-IRA timing within the §72(t)(6)(A) 2-year period does not by itself disqualify a 59½+ or exception-covered distribution — it only affects the RATE of a genuinely early, no-exception distribution, which this engine does not compute. CALIFORNIA DIVERGES on that rate and this engine computes it for neither jurisdiction: CA's analogue is 2.5% (R&TC §17085(c)(1)), 6% where §72(t)(6) applies (§17085(c)(2)), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax. THE 2-YEAR CLOCK IS ANCHORED TO PARTICIPATION IN THE EMPLOYER'S PLAN, NOT THE ACCOUNT'S AGE: §72(t)(6)(A) runs the period from 'the date such individual first participated in any qualified salary reduction arrangement maintained by the individual's employer under section 408(p)(2)', and IRS Notice 98-4 Q&A I-5 gives the operational start — 'the first day on which contributions made by the individual's employer are deposited in the individual's SIMPLE IRA' (the Form 5329 instructions and FTB 3805P agree). It is measured PER EMPLOYER, so a new employer's SIMPLE starts a NEW 2-year period for that employer's own contributions — reading the clock as the ACCOUNT's age can UNDER-tax at 10%/2.5%. A transfer or rollover between SIMPLE IRAs under the SAME employer's arrangement does not restart it. ACROSS EMPLOYERS THE PERIOD FOLLOWS EACH EMPLOYER'S OWN CONTRIBUTIONS — 26 CFR §1.408A-4 A-4(b): 'This 2-year period of section 408(d)(3)(G) applies separately to the contributions of each of an individual's employers maintaining a SIMPLE IRA Plan' — and A-4(b) itself identifies that period as 'the 2-year period described in section 72(t)(6)', so it is THIS period, not a rollover-only clock. The rule it construes is §408(d)(3)(G)'s restriction on conversions; applying the same contribution-tracing to the RATE is this engine's reading of it. It runs BOTH ways. Dollars traceable to a prior employer whose period has EXPIRED keep that expiry and are NOT pulled into the new employer's open window. Dollars traceable to a prior employer whose period is STILL OPEN carry it into the new account and stay at 25%/6% even after the receiving employer's own window closes — until that prior period itself expires, not indefinitely. Where provenance cannot be substantiated, treat the amount as still inside a 2-year period (25%/6% — federal and CA respectively; NY has no analogous additional tax) rather than assuming the lower rate. |
| pensionDistributionIsNonqualifiedAnnuityNiiboolean | NOT the same contract as the federal endpoint — on /state this field is REQUIRED (else ny_private_pension_exclusion_classification_needed decline) whenever…NOT the same contract as the federal endpoint — on /state this field is REQUIRED (else ny_private_pension_exclusion_classification_needed decline) whenever nyPrivatePensionQualifiesFor20kExclusion:true is claimed on a positive pension, UNCONDITIONALLY, regardless of whether federal §1411 NIIT materiality would independently require it — NY IT-201-I's own negative list for the line-29 $20,000 exclusion excludes a nonqualified commercial annuity, a fact the federal-only materiality gate can leave unaffirmed below the NIIT threshold. true (a nonqualified commercial annuity) is also flatly inconsistent with nyPensionIsGovernmentPension:true or nyPrivatePensionQualifiesFor20kExclusion:true → decline (pension_exclusion_classification_ambiguous), and with CA's caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true → decline (ca_pension_exclusion_classification_ambiguous). IL: must be false to use ilPensionIsQualifiedRetirementIncomeAffirmed (else il_needs_review). |
| pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmedboolean | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true AND pensionDistributionIsNonqualifiedAnnuityNii is NOT explicitly false — see the federal endpoint's own field description for the full §72(q)(2) accept-list citation. |
| pensionDistributionEarlyWithdrawalBasisIsAvailableForThisPlanTypeAffirmedboolean | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — see the federal endpoint's own field description for the full plan-type-divergence citation. |
| pensionDistributionNoSeppModificationRecaptureAffirmedtrue | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — see the federal endpoint's own field description for the full SEPP-modification-recapture citation. |
| socialSecurityBenefitsnumber | Social Security benefits (SSA-1099 box 5, box 3 less box 4).Social Security benefits (SSA-1099 box 5, box 3 less box 4). CA, NY, IL, NC and MI FULLY EXCLUDE taxable Social Security: the engine recomputes the federal §86 taxable portion (line 6b) in-process and SUBTRACTS it on Schedule CA (540) line 6 col B (CA) / IT-201 line 27 (NY) / IL-1040 line 5 / D-400 line 9 / MI-1040 line 13. REQUIRES socialSecurityStandardCaseAffirmed:true (and socialSecurityMfsLivedWithSpouse for MFS) — the SAME §86 gates as the federal endpoint; an unaffirmed SS return declines federally → declines the state. |
| taxExemptInterestnumber | Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand.Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand. IL, NC and MI: REQUIRED (0 if none), added in full (IL-1040 line 2, D-400 line 7, MI-1040 line 11). CA/NY: accepted so the federal §86 recompute is correct, BUT any positive amount DECLINES the state return (state_tax_exempt_interest_unsupported): the CA out-of-state-muni add-back (Schedule CA line 2 col C) / NY non-NY-muni add-back (IT-225 A-101) is not sized in this slice. |
| socialSecurityStandardCaseAffirmedtrue | §6694 affirmation REQUIRED when socialSecurityBenefits is supplied:§6694 affirmation REQUIRED when socialSecurityBenefits is supplied: attests the standard §86 worksheet applies (no lump-sum election, no Form 8815, §137, §85(c), foreign-earned-income or §931-933 add-backs, no Roth-conversion or other provisional-income complications the engine does not model). Absent → declines (fail-closed). |
| socialSecurityMfsLivedWithSpouseboolean | REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately:REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately: whether the taxpayer lived with their spouse at any time during the year (§86(c)(1)(C) sets the MFS base amount to $0 if true). Absent for MFS+SS → declines. |
| noForeignOrTerritoryExclusionAffirmedbooleanrequired | Same as FederalProfile.noForeignOrTerritoryExclusionAffirmed; false declines a CA, NY, IL, NC or MI return (as federal_declined). |
| taxExemptInterestNoPrivateActivityBondstrue | §6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g).§6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g). Required with a positive taxExemptInterest on IL, NC and MI; on CA/NY a positive amount declines regardless. |
| estateTrustK1NoAmtAdjustmentAffirmedtrue | §6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest.§6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest. WHAT `true` ATTESTS: no Schedule K-1 (Form 1041) received for this tax year, from any estate or trust, shows a positive amount in box 12 code A (adjustment for minimum tax purposes, Form 6251 line 2j) or any amount, positive or negative, in box 12 codes B through I. Attest true if no such K-1 was received, or if every code A amount is zero or negative and codes B through I are blank on all of them (a negative code A left out over-states the tax). The engine sets line 2j to $0. Absent or false with any of those inputs: the return declines (estate_trust_amt_adjustment_unmodeled); true with none of them: declined as an orphan; false always declines (a preparer completes Form 6251). Never default it. Not detected: a K-1 with a code A or B-I amount but no income boxes, on a return with none of those inputs. |
| otherIncomePresentButUnmodeledarray of string | Same as FederalProfile.otherIncomePresentButUnmodeled; on /state the decline arrives as federal_declined. |
| stateenum (14 values)required | ca, ny, il, nc, mi, or a no-income-tax state ($0 or a decline). Any other state is rejected. |
| residency"full_year_resident" | "part_year_resident" | "part_year" | "nonresident" | "non_resident" | Residency for the year; only a full-year resident computes, part-year and nonresident decline. |
| canBeClaimedAsDependentbooleanrequired | Required. true when another taxpayer can claim this filer (on a joint return, either spouse) as a dependent; CA, NY and IL decline true (dependent_filer_needs_review); NC and MI compute a single or…Required. true when another taxpayer can claim this filer (on a joint return, either spouse) as a dependent; CA, NY and IL decline true (dependent_filer_needs_review); NC and MI compute a single or married_filing_separately dependent filer who claims no dependents (NC full standard deduction; MI $1,500), and a no-income-tax state's $0 is unchanged. |
| ncNoAdditionsAffirmedboolean | NC only, required true (else the NC return declines):NC only, required true (else the NC return declines): the North Carolina additions to federal AGI (G.S. 105-153.5(c), (c1), (c2) and (c3) and 105-153.6) are $0 for this year apart from interest on other states' obligations, which the engine adds from taxExemptInterest — including Opportunity Zone deferred or excluded gain, a federal basis above the state basis on property sold, employer student-loan payments excluded from wages, excluded principal-residence or student-loan debt discharge, non-qualified North Carolina 529 withdrawals, pass-through and business add-backs, and any add-back the Department requires for a federal change made after the year's Internal Revenue Code reference date. |
| ncFilingStatusMatchesFederalAffirmedboolean | NC only, required true (else declines): the North Carolina filing status is the federal filing status, and on a joint return both spouses were full-year North Carolina residents. |
| ncStandardDeductionAllowedAffirmedboolean | NC only, required true (else declines):NC only, required true (else declines): the North Carolina standard deduction is allowed: the filer is not married filing separately with a spouse who itemizes on the federal or North Carolina return, is not a nonresident or dual-status alien, and is not filing a short-period return. |
| ncChildrenAllowedFederalCtcinteger | NC only: children for whom the federal child tax credit was allowed this year (Schedule 8812 qualifying children with the required SSN; from 2025 the filer, or on a joint return one spouse, also needs…NC only: children for whom the federal child tax credit was allowed this year (Schedule 8812 qualifying children with the required SSN; from 2025 the filer, or on a joint return one spouse, also needs a valid SSN, or no credit is allowed and this is 0; for 2021, only those under 17), for the D-400 line 10 child deduction. A dependent filer with children declines. Omitted = 0 (an over-tax). With children, federal AGI within $100 of a child-deduction band edge declines. |
curl https://tax-mcp.com/api/mcp/tax-compute/state \
-H "Authorization: Bearer $TAX_MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"state": "nc",
"year": 2025,
"filingStatus": "married_filing_jointly",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 70000,
"medicareWages": 70000,
"taxExemptInterest": 0,
"ncChildrenAllowedFederalCtc": 2,
"ncNoAdditionsAffirmed": true,
"ncFilingStatusMatchesFederalAffirmed": true,
"ncStandardDeductionAllowedAffirmed": true
}'{
"computed": true,
"state": "nc",
"year": 2025,
"filingStatus": "married_filing_jointly",
"federalAGI": 70000,
"taxableIncome": 40500,
"incomeTax": 1721,
"additionalTaxes": [],
"totalTax": 1721,
"notEvaluated": [
"2026: the child deduction keys on the federal child tax credit under the Code as of January 1, 2023 (G.S. 105-228.90); a return whose credit under that Code is $0 declines",
"credits (Form D-400TC: tax paid to another state or country, rehabilitation and business credits) — over-tax",
"Schedule S deductions other than taxable Social Security (U.S. obligation interest, Bailey-settlement and uniformed-services retirement, Tier 2 railroad retirement in the pension line) — over-tax",
"North Carolina itemized deductions (mortgage interest and property tax up to $20,000, charitable, medical) — the standard deduction is used — over-tax",
"interest on North Carolina obligations is added with the rest of taxExemptInterest — over-tax",
"for 2021, the child deduction counts children under 17 only (the D-401 worksheet), not the federal 2021 age — at most an over-tax",
"consumer use tax (D-400 line 18) — under-tax when owed",
"line 6 is federal AGI; the same return rounded otherwise can show a different AGI (not_modeled.cents_rounding), moving the tax by up to the year's rate times the difference plus $1; with children, within $100 of a child-deduction band edge the return declines, and a larger difference there can change the band undetected",
"North Carolina payments, refund, estimated-tax interest (Form D-422) and the filing requirement"
],
"attestationsRelied": [
"ncNoAdditionsAffirmed",
"ncFilingStatusMatchesFederalAffirmed",
"ncStandardDeductionAllowedAffirmed"
],
"lines": [
{ "lineId": "D-400:6", "label": "Federal adjusted gross income", "amount": 70000 },
{
"lineId": "D-400:7",
"label": "Additions (interest on other states' obligations)",
"amount": 0
},
{ "lineId": "D-400:8", "label": "Line 6 plus line 7", "amount": 70000 },
{ "lineId": "D-400:9", "label": "Deductions (taxable Social Security)", "amount": 0 },
{ "lineId": "D-400:10b", "label": "Child deduction", "amount": 4000 },
{ "lineId": "D-400:11", "label": "North Carolina standard deduction", "amount": 25500 },
{ "lineId": "D-400:12a", "label": "Total of lines 9, 10b and 11", "amount": 29500 },
{ "lineId": "D-400:14", "label": "North Carolina taxable income", "amount": 40500 },
{ "lineId": "D-400:15", "label": "North Carolina income tax (4.25%)", "amount": 1721 }
],
"flags": [],
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "nc", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "<computation-support notice — see full response>"
}
}Full response, including line derivations
{
"computed": true,
"state": "nc",
"year": 2025,
"filingStatus": "married_filing_jointly",
"federalAGI": 70000,
"taxableIncome": 40500,
"incomeTax": 1721,
"additionalTaxes": [],
"totalTax": 1721,
"notEvaluated": [
"2026: the child deduction keys on the federal child tax credit under the Code as of January 1, 2023 (G.S. 105-228.90); a return whose credit under that Code is $0 declines",
"credits (Form D-400TC: tax paid to another state or country, rehabilitation and business credits) — over-tax",
"Schedule S deductions other than taxable Social Security (U.S. obligation interest, Bailey-settlement and uniformed-services retirement, Tier 2 railroad retirement in the pension line) — over-tax",
"North Carolina itemized deductions (mortgage interest and property tax up to $20,000, charitable, medical) — the standard deduction is used — over-tax",
"interest on North Carolina obligations is added with the rest of taxExemptInterest — over-tax",
"for 2021, the child deduction counts children under 17 only (the D-401 worksheet), not the federal 2021 age — at most an over-tax",
"consumer use tax (D-400 line 18) — under-tax when owed",
"line 6 is federal AGI; the same return rounded otherwise can show a different AGI (not_modeled.cents_rounding), moving the tax by up to the year's rate times the difference plus $1; with children, within $100 of a child-deduction band edge the return declines, and a larger difference there can change the band undetected",
"North Carolina payments, refund, estimated-tax interest (Form D-422) and the filing requirement"
],
"attestationsRelied": [
"ncNoAdditionsAffirmed",
"ncFilingStatusMatchesFederalAffirmed",
"ncStandardDeductionAllowedAffirmed"
],
"lines": [
{ "lineId": "D-400:6", "label": "Federal adjusted gross income", "amount": 70000 },
{
"lineId": "D-400:7",
"label": "Additions (interest on other states' obligations)",
"amount": 0
},
{ "lineId": "D-400:8", "label": "Line 6 plus line 7", "amount": 70000 },
{ "lineId": "D-400:9", "label": "Deductions (taxable Social Security)", "amount": 0 },
{ "lineId": "D-400:10b", "label": "Child deduction", "amount": 4000 },
{ "lineId": "D-400:11", "label": "North Carolina standard deduction", "amount": 25500 },
{ "lineId": "D-400:12a", "label": "Total of lines 9, 10b and 11", "amount": 29500 },
{ "lineId": "D-400:14", "label": "North Carolina taxable income", "amount": 40500 },
{ "lineId": "D-400:15", "label": "North Carolina income tax (4.25%)", "amount": 1721 }
],
"flags": [],
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "nc", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}
}Request body: Michigan
"state": "mi". 65 fields.
| Field | Description |
|---|---|
| yearintegerrequired | Tax year; a year the state engine does not model declines. |
| filingStatus"single" | "married_filing_jointly" | "married_filing_separately" | "head_of_household"required | REQUIRED. The state endpoint re-runs the FEDERAL pipeline to derive its starting point, so it needs the same filing status the federal endpoint does. |
| wagesnumber | Same as FederalProfile.wages. |
| medicareWagesnumber | Medicare wages (W-2 box 5). CONDITIONALLY REQUIRED, and the condition cannot be expressed in this schema's `required` array, which is why it is spelled out here. This endpoint re-runs the FEDERAL…Medicare wages (W-2 box 5). CONDITIONALLY REQUIRED, and the condition cannot be expressed in this schema's `required` array, which is why it is spelled out here. This endpoint re-runs the FEDERAL pipeline, and that pipeline declines its Additional Medicare Tax determination whenever box 5 is omitted AND at least one of the federal pipeline's W-2 evidence fields is POSITIVE (the trigger is a positive amount, not mere presence: an explicit 0 does not arm it). Those fields are `wages`, `federalWithholding`, `medicareTaxWithheld` and `socialSecurityWages`, and this endpoint accepts all four, so a positive value in any of them arms it. WHAT A STATE CALLER ACTUALLY RECEIVES: `computed:false` with code `federal_declined` - NOT the federal-side code `surtax_additional_medicare`, which this endpoint does not surface; the box-5 explanation arrives in `reason`. Rationale: box 5 can exceed box 1 by an unbounded amount for real filers - 401(k)/403(b)/457(b) elective deferrals reduce box 1 while remaining subject to Medicare tax - so no finite margin can rule out the Additional Medicare Tax threshold being crossed at box 5. It is NOT required in the absence of positive W-2 evidence: a dividends-only or zero-wage return computes without it. Declared because a caller building exactly what this schema prescribes must be able to learn this requirement from the schema itself. |
| federalWithholdingnumber | Same as FederalProfile.federalWithholding. |
| medicareTaxWithheldnumber | Same as FederalProfile.medicareTaxWithheld. |
| taxableInterestnumber | CA/NY: requires stateIncomeConformsToFederal:true (else non-wage income declines); IL, NC and MI take it without. |
| ordinaryDividendsnumber | CA/NY: requires stateIncomeConformsToFederal:true. |
| qualifiedDividendsnumber | ≤ ordinaryDividends; CA/NY/IL/NC/MI tax it as ordinary (no preferential rate); CA/NY require stateIncomeConformsToFederal:true. |
| reit199ADividendsnumber | Same as FederalProfile.reit199ADividends. |
| netShortTermCapGainnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Taxed as ordinary by CA/NY/IL/NC/MI; CA/NY require stateIncomeConformsToFederal:true. |
| netLongTermCapGainnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Taxed as ordinary by CA/NY/IL/NC/MI; CA/NY require stateIncomeConformsToFederal:true. |
| priorYearCapLossCarryoverSTnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year SHORT-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Applied with the §1211(b) −$3,000 (−$1,500 MFS) annual limit. THIS ENDPOINT DOES NOT RETURN AN ENDING CARRYOVER: endingCapLossCarryoverST is a FEDERAL-response field and the state response has no equivalent, so track the remaining carryover yourself or read it from /federal. This field is the PRIOR-YEAR carryover only — do NOT also net it into netShortTermCapGain/netLongTermCapGain, which are CURRENT-YEAR nets before any carryover; doing both applies it twice (an executed $12,120 under-tax). Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. Accepted on the STATE endpoint for the same reason: this endpoint re-runs the federal pipeline, so this field's presence arms the identical Schedule-D-presence affirmation gates described above, and a caller who omits a zero-net carryover here bypasses them exactly as on /federal. If only an AMT-side carryover exists, send 0 (the return declines). |
| priorYearCapLossCarryoverLTnumber | CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year LONG-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Nets against long-term gain. THIS ENDPOINT DOES NOT RETURN AN ENDING CARRYOVER: endingCapLossCarryoverLT is a FEDERAL-response field and the state response has no equivalent, so track the remaining carryover yourself or read it from /federal. Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. Accepted on the STATE endpoint for the same reason: this endpoint re-runs the federal pipeline, so this field's presence arms the identical Schedule-D-presence affirmation gates described above, and a caller who omits a zero-net carryover here bypasses them exactly as on /federal. If only an AMT-side carryover exists, send 0 (the return declines). |
| capLossCarryoverNoAmtDifferenceAffirmedtrue | §6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the trigger is PRESENCE, not magnitude, and not the carryover field specifically.§6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the trigger is PRESENCE, not magnitude, and not the carryover field specifically. WHAT `true` ATTESTS (identical to FederalProfile.capLossCarryoverNoAmtDifferenceAffirmed): EITHER (a) this return has no prior-year capital-loss carryover at all, for regular tax or AMT — the common case, and attesting true is how you say so — OR (b) a carryover exists and its ENTERING AMT-SIDE amount equals its regular-tax amount. It covers a carryover HOWEVER it reached this engine, including one the caller already netted into netShortTermCapGain/netLongTermCapGain, and it additionally attests the carryover was NOT supplied BOTH ways (netted into a scalar AND as priorYearCapLossCarryover*), which would apply it twice. DO NOT SUPPLY IT DEFENSIVELY: on a return carrying NO Schedule D input at all this is a contradictory orphan affirmation and the return is DECLINED - a state caller receives `computed:false` with code `federal_declined`, the orphan explanation in `reason`. An AMT-only carryover is NOT covered: send priorYearCapLossCarryoverST/LT as 0, and the return declines. |
| mortgageInterestnumber | Same as FederalProfile.mortgageInterest. |
| mortgageAvgBalancenumber | Same as FederalProfile.mortgageAvgBalance. |
| mortgageInterestExcludesExcessRefinancingProceedsboolean | Same as FederalProfile.mortgageInterestExcludesExcessRefinancingProceeds. |
| mortgageInterestSecuresAmtQualifiedDwellingboolean | Same as FederalProfile.mortgageInterestSecuresAmtQualifiedDwelling. |
| mortgageInterestSecuresSec121PrincipalResidenceboolean | Same as FederalProfile.mortgageInterestSecuresSec121PrincipalResidence. |
| foreignTaxPaidnumber | Same as FederalProfile.foreignTaxPaid. |
| foreignIncomeAllPassive1099true | Same as FederalProfile.foreignIncomeAllPassive1099: all foreign income is passive and shown on a qualified payee statement (§6724(d)(2)), which is broader than the 1099 family. |
| foreignTaxIsFullyCreditableAffirmedtrue | Same as FederalProfile.foreignTaxIsFullyCreditableAffirmed. |
| foreignSourceGrossIncomenumber | Same as FederalProfile.foreignSourceGrossIncome. |
| foreignQualifiedDividendsAndCapGainsnumber | Same as FederalProfile.foreignQualifiedDividendsAndCapGains. |
| foreignTaxNoCarryoverAffirmedtrue | Same as FederalProfile.foreignTaxNoCarryoverAffirmed. |
| foreignSourceNoForm1116PartILines2Through5EntryAffirmedtrue | Same as FederalProfile.foreignSourceNoForm1116PartILines2Through5EntryAffirmed. |
| foreignSourceNoForm1116Line16AdjustmentAffirmedtrue | Same as FederalProfile.foreignSourceNoForm1116Line16AdjustmentAffirmed. |
| foreignTaxNoForm1116Line12ReductionAffirmedtrue | Same as FederalProfile.foreignTaxNoForm1116Line12ReductionAffirmed. |
| stateLocalIncomeTaxnumber | Same as FederalProfile.stateLocalIncomeTax. |
| realEstateTaxnumber | Same as FederalProfile.realEstateTax. |
| sec1250UnrecapturedGainnumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.sec1250UnrecapturedGain. |
| collectibles28Gainnumber | CONTAINER SCALAR — omitting it asserts the schedule does not exist; send 0 for a zero net. Same as FederalProfile.collectibles28Gain. |
| specialRateGainNoAmtScheduleDDifferenceAffirmedboolean | Same as FederalProfile.specialRateGainNoAmtScheduleDDifferenceAffirmed. |
| collectibles28NoSec1202ExclusionPreferenceAffirmedtrue | §6694 affirmation REQUIRED on the same Schedule-D-presence trigger.§6694 affirmation REQUIRED on the same Schedule-D-presence trigger. WHAT `true` ATTESTS (identical to FederalProfile.collectibles28NoSec1202ExclusionPreferenceAffirmed): EITHER no §1202 qualified-small-business-stock exclusion is involved on this return at all, OR every §1202 exclusion claimed arises solely from stock acquired AFTER 2010-09-27 and so carries no §57(a)(7) AMT preference. This engine hardcodes AMT other-preferences to $0, so an unattested pre-2010-09-28 exclusion would UNDER-state AMT — and the preference is 7% of the EXCLUDED gain, which no input here carries and which netting cannot reduce, so it survives even when every capital-gain figure on the return nets to $0. That is why the trigger is presence of Schedule D activity rather than a positive amount. DO NOT SUPPLY IT DEFENSIVELY: on a return carrying NO Schedule D input at all this is a contradictory orphan affirmation and the return is DECLINED - a state caller receives `computed:false` with code `federal_declined`, the orphan explanation in `reason`. |
| qbiDeductionnumber | Same as FederalProfile.qbiDeduction; on /state the decline arrives as federal_declined. |
| pensionDistributionTaxablenumber | State (CA, NY, IL, NC, MI) — the fully-taxable federal line-4b/5b pension/IRA distribution (with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true).State (CA, NY, IL, NC, MI) — the fully-taxable federal line-4b/5b pension/IRA distribution (with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true). IL subtracts it with ilPensionIsQualifiedRetirementIncomeAffirmed; NC taxes it (its retirement deductions are not modeled, an over-tax); MI: see miNoRetirementOrAgeDeductionsAffirmed and miRetirementFactsAffirmed. NY EXCLUDES it: supply nyPensionIsGovernmentPension (IT-201 line 26, full) OR nyPrivatePensionQualifiesFor20kExclusion (IT-201 line 29, min($20k,5b)); neither → the pension stays NY-taxable. CA CONFORMS and TAXES it by default, with ONE modeled exclusion: caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true excludes min($20,000, line 5b), AGI-gated (R&TC §§17132.9/17132.10) — and a VERIFY flag names the unmodeled CA divergences enumerated in CA_COMPUTE_CAPABILITY.state_adjustments.pension (served on GET /api/mcp/tax-compute/state), which is the single authoritative list — this text states no count of its own, because a count restated in many places is a claim that must be maintained in many places, and on this surface it was not. (1) Tier-2 railroad retirement (RRB-1099-R), which CA EXCLUDES (45 U.S.C. §231m) — omitting it OVER-taxes. (2) CA's early-distribution additional tax, which this engine computes for NEITHER jurisdiction: 2.5% (R&TC §17085(c)(1)), raised to 6% where §72(t)(6) applies (§17085(c)(2), FTB 3805P line 4), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax — omitting THIS one UNDER-taxes. (3) An IRA-to-HSA one-time funding distribution under §408(d)(9), EXCLUDED from federal gross income under §408(d)(9)(A) but which California conforms out entirely (R&TC §17215.4) — the FTB 3805P instructions require it ADDED BACK to CA AGI, and — where the distribution is premature under the §72(t) rules — a 2 1/2% additional tax, which can be owed even where no federal §72(t) tax is. This one runs the OPPOSITE way from (1): omitting it UNDER-taxes California, and the engine has no field for it, so a CA return carrying one is outside the modeled surface. |
| pensionDistributionFullyTaxableAffirmedtrue | §6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint, one of TWO required affirmations):§6694 affirmation REQUIRED for a positive pensionDistributionTaxable (same contract as the federal endpoint, one of TWO required affirmations): the fully-taxable 1099-R box 2a distribution, no basis/QCD/rollover/Roth/NUA. |
| pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmedtrue | §6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed (same contract as the federal endpoint).§6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed (same contract as the federal endpoint). THIS SCHEMA DELIBERATELY DOES NOT RESTATE THE RULE — see the federal endpoint's field of this name for the operative condition, which GOVERNS. (fed-pension-5b-72q-levy-exception-fix, 2026-08-29 — see the federal endpoint's pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmed field, required on the SAME contract here whenever this field is true and pensionDistributionIsNonqualifiedAnnuityNii is not explicitly false; and pensionDistributionNoSeppModificationRecaptureAffirmed, required on the SAME contract here whenever this field is true — regardless of which specific basis — per fed-pension-5b-sepp-modification-recapture-gate, 2026-08-29). SIMPLE-IRA timing within the §72(t)(6)(A) 2-year period does not by itself disqualify a 59½+ or exception-covered distribution — it only affects the RATE of a genuinely early, no-exception distribution, which this engine does not compute. CALIFORNIA DIVERGES on that rate and this engine computes it for neither jurisdiction: CA's analogue is 2.5% (R&TC §17085(c)(1)), 6% where §72(t)(6) applies (§17085(c)(2)), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax. THE 2-YEAR CLOCK IS ANCHORED TO PARTICIPATION IN THE EMPLOYER'S PLAN, NOT THE ACCOUNT'S AGE: §72(t)(6)(A) runs the period from 'the date such individual first participated in any qualified salary reduction arrangement maintained by the individual's employer under section 408(p)(2)', and IRS Notice 98-4 Q&A I-5 gives the operational start — 'the first day on which contributions made by the individual's employer are deposited in the individual's SIMPLE IRA' (the Form 5329 instructions and FTB 3805P agree). It is measured PER EMPLOYER, so a new employer's SIMPLE starts a NEW 2-year period for that employer's own contributions — reading the clock as the ACCOUNT's age can UNDER-tax at 10%/2.5%. A transfer or rollover between SIMPLE IRAs under the SAME employer's arrangement does not restart it. ACROSS EMPLOYERS THE PERIOD FOLLOWS EACH EMPLOYER'S OWN CONTRIBUTIONS — 26 CFR §1.408A-4 A-4(b): 'This 2-year period of section 408(d)(3)(G) applies separately to the contributions of each of an individual's employers maintaining a SIMPLE IRA Plan' — and A-4(b) itself identifies that period as 'the 2-year period described in section 72(t)(6)', so it is THIS period, not a rollover-only clock. The rule it construes is §408(d)(3)(G)'s restriction on conversions; applying the same contribution-tracing to the RATE is this engine's reading of it. It runs BOTH ways. Dollars traceable to a prior employer whose period has EXPIRED keep that expiry and are NOT pulled into the new employer's open window. Dollars traceable to a prior employer whose period is STILL OPEN carry it into the new account and stay at 25%/6% even after the receiving employer's own window closes — until that prior period itself expires, not indefinitely. Where provenance cannot be substantiated, treat the amount as still inside a 2-year period (25%/6% — federal and CA respectively; NY has no analogous additional tax) rather than assuming the lower rate. |
| pensionDistributionIsNonqualifiedAnnuityNiiboolean | NOT the same contract as the federal endpoint — on /state this field is REQUIRED (else ny_private_pension_exclusion_classification_needed decline) whenever…NOT the same contract as the federal endpoint — on /state this field is REQUIRED (else ny_private_pension_exclusion_classification_needed decline) whenever nyPrivatePensionQualifiesFor20kExclusion:true is claimed on a positive pension, UNCONDITIONALLY, regardless of whether federal §1411 NIIT materiality would independently require it — NY IT-201-I's own negative list for the line-29 $20,000 exclusion excludes a nonqualified commercial annuity, a fact the federal-only materiality gate can leave unaffirmed below the NIIT threshold. true (a nonqualified commercial annuity) is also flatly inconsistent with nyPensionIsGovernmentPension:true or nyPrivatePensionQualifiesFor20kExclusion:true → decline (pension_exclusion_classification_ambiguous), and with CA's caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true → decline (ca_pension_exclusion_classification_ambiguous). IL: must be false to use ilPensionIsQualifiedRetirementIncomeAffirmed (else il_needs_review). |
| pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmedboolean | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true AND pensionDistributionIsNonqualifiedAnnuityNii is NOT explicitly false — see the federal endpoint's own field description for the full §72(q)(2) accept-list citation. |
| pensionDistributionEarlyWithdrawalBasisIsAvailableForThisPlanTypeAffirmedboolean | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — see the federal endpoint's own field description for the full plan-type-divergence citation. |
| pensionDistributionNoSeppModificationRecaptureAffirmedtrue | Required on the same contract as the federal endpoint.Required on the same contract as the federal endpoint. Same contract as the federal endpoint's field of this name: REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — see the federal endpoint's own field description for the full SEPP-modification-recapture citation. |
| socialSecurityBenefitsnumber | Social Security benefits (SSA-1099 box 5, box 3 less box 4).Social Security benefits (SSA-1099 box 5, box 3 less box 4). CA, NY, IL, NC and MI FULLY EXCLUDE taxable Social Security: the engine recomputes the federal §86 taxable portion (line 6b) in-process and SUBTRACTS it on Schedule CA (540) line 6 col B (CA) / IT-201 line 27 (NY) / IL-1040 line 5 / D-400 line 9 / MI-1040 line 13. REQUIRES socialSecurityStandardCaseAffirmed:true (and socialSecurityMfsLivedWithSpouse for MFS) — the SAME §86 gates as the federal endpoint; an unaffirmed SS return declines federally → declines the state. |
| taxExemptInterestnumber | Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand.Tax-exempt interest (1040 line 2a) — a §86 provisional-income operand. IL, NC and MI: REQUIRED (0 if none), added in full (IL-1040 line 2, D-400 line 7, MI-1040 line 11). CA/NY: accepted so the federal §86 recompute is correct, BUT any positive amount DECLINES the state return (state_tax_exempt_interest_unsupported): the CA out-of-state-muni add-back (Schedule CA line 2 col C) / NY non-NY-muni add-back (IT-225 A-101) is not sized in this slice. |
| socialSecurityStandardCaseAffirmedtrue | §6694 affirmation REQUIRED when socialSecurityBenefits is supplied:§6694 affirmation REQUIRED when socialSecurityBenefits is supplied: attests the standard §86 worksheet applies (no lump-sum election, no Form 8815, §137, §85(c), foreign-earned-income or §931-933 add-backs, no Roth-conversion or other provisional-income complications the engine does not model). Absent → declines (fail-closed). |
| socialSecurityMfsLivedWithSpouseboolean | REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately:REQUIRED (either boolean) when socialSecurityBenefits is supplied AND filingStatus is married_filing_separately: whether the taxpayer lived with their spouse at any time during the year (§86(c)(1)(C) sets the MFS base amount to $0 if true). Absent for MFS+SS → declines. |
| noForeignOrTerritoryExclusionAffirmedbooleanrequired | Same as FederalProfile.noForeignOrTerritoryExclusionAffirmed; false declines a CA, NY, IL, NC or MI return (as federal_declined). |
| taxExemptInterestNoPrivateActivityBondstrue | §6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g).§6694 affirmation paired with taxExemptInterest for the federal §86/AMT path (attests no specified private-activity-bond interest, Form 6251 line 2g). Required with a positive taxExemptInterest on IL, NC and MI; on CA/NY a positive amount declines regardless. |
| estateTrustK1NoAmtAdjustmentAffirmedtrue | §6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest.§6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest. WHAT `true` ATTESTS: no Schedule K-1 (Form 1041) received for this tax year, from any estate or trust, shows a positive amount in box 12 code A (adjustment for minimum tax purposes, Form 6251 line 2j) or any amount, positive or negative, in box 12 codes B through I. Attest true if no such K-1 was received, or if every code A amount is zero or negative and codes B through I are blank on all of them (a negative code A left out over-states the tax). The engine sets line 2j to $0. Absent or false with any of those inputs: the return declines (estate_trust_amt_adjustment_unmodeled); true with none of them: declined as an orphan; false always declines (a preparer completes Form 6251). Never default it. Not detected: a K-1 with a code A or B-I amount but no income boxes, on a return with none of those inputs. |
| otherIncomePresentButUnmodeledarray of string | Same as FederalProfile.otherIncomePresentButUnmodeled; on /state the decline arrives as federal_declined. |
| stateenum (14 values)required | ca, ny, il, nc, mi, or a no-income-tax state ($0 or a decline). Any other state is rejected. |
| residency"full_year_resident" | "part_year_resident" | "part_year" | "nonresident" | "non_resident" | Residency for the year; only a full-year resident computes, part-year and nonresident decline. |
| canBeClaimedAsDependentbooleanrequired | Required. true when another taxpayer can claim this filer (on a joint return, either spouse) as a dependent; CA, NY and IL decline true (dependent_filer_needs_review); NC and MI compute a single or…Required. true when another taxpayer can claim this filer (on a joint return, either spouse) as a dependent; CA, NY and IL decline true (dependent_filer_needs_review); NC and MI compute a single or married_filing_separately dependent filer who claims no dependents (NC full standard deduction; MI $1,500), and a no-income-tax state's $0 is unchanged. |
| miNoAdditionsAffirmedboolean | MI only, required true (else the MI return declines):MI only, required true (else the MI return declines): the Michigan additions to federal AGI (MCL 206.30(1)) are $0 for this year apart from interest on other states' obligations, which the engine adds from taxExemptInterest — including taxes on or measured by income deducted in arriving at AGI and an allocated share of electing flow-through entity tax, non-qualified Michigan education savings (MESP) or MiABLE withdrawals, any non-qualified withdrawal from a Michigan first-time home buyer savings account, a refunded MET contract or MET loan default, a federal net operating loss, Internal Revenue Code decoupling adjustments, and every other addition. |
| miCapitalGainsSameForMichiganAffirmedboolean | MI only, required true whenever any capital gain or loss input is sent (any of netShortTermCapGain, netLongTermCapGain, priorYearCapLossCarryoverST, priorYearCapLossCarryoverLT, sec1250UnrecapturedGain, collectibles28Gain, each alone included):MI only, required true whenever any capital gain or loss input is sent (any of netShortTermCapGain, netLongTermCapGain, priorYearCapLossCarryoverST, priorYearCapLossCarryoverLT, sec1250UnrecapturedGain, collectibles28Gain, each alone included): the Michigan capital gain or loss equals the federal one (MI-1040D Part 3 line 12 or 13: column G equals column F): no gain or loss on U.S. obligations, no gain or loss on real or tangible personal property located outside Michigan, no §271 election, and the Michigan capital-loss carryover equals the federal one (after any year an MI-1040D was filed it is figured from MI-1040 line 12 minus line 13 and can be smaller). |
| miFilingStatusMatchesAffirmedboolean | MI only, required true (else declines):MI only, required true (else declines): the Michigan filing status is single for a federal single or head-of-household return and matches a federal joint or separate return (a federal separate return filed jointly in Michigan, and a qualifying surviving spouse sent as married_filing_jointly — single in Michigan — are not covered), and on a joint return both spouses were full-year Michigan residents. |
| miNoRetirementOrAgeDeductionsAffirmedboolean | MI only: this or miRetirementFactsAffirmed must be true (neither, or both, declines): nothing on this return qualifies for the Michigan retirement and pension subtraction (Form 4884, any birth-year…MI only: this or miRetirementFactsAffirmed must be true (neither, or both, declines): nothing on this return qualifies for the Michigan retirement and pension subtraction (Form 4884, any birth-year tier or the Lowering MI Costs Act phase-in), the Tier 2 or Tier 3 standard deduction, the interest, dividends and capital gains deduction for a filer born before 1946 or the unremarried surviving spouse of a decedent born before 1946 who died after reaching 65, or the military, Michigan National Guard or railroad retirement subtraction. |
| miRetirementFactsAffirmedboolean | MI only, instead of miNoRetirementOrAgeDeductionsAffirmed:MI only, instead of miNoRetirementOrAgeDeductionsAffirmed: the Tier 2 or Tier 3 standard deduction or the 2023-2025 Form 4884 Section D phase-in, for a key person (the filer; on a joint return the older spouse) born 1946 or later, 2020-2025. Requires miFilerBirthYear (and miSpouseBirthYear on a joint return). Attests: miFilerBirthYear and miSpouseBirthYear are each person's own year of birth, and a born-on-January-1 flag is true only for a person born on January 1; no person whose birth year is sent (the filer or the spouse) died during the tax year; no surviving-spouse election, no deceased spouse's birth year and no interest, dividends and capital gains deduction as the unremarried surviving spouse of a decedent born before 1946 applies; no SSA-exempt government retirement benefits; no public-safety retirement benefits under MCL 206.30(11); no military, Michigan National Guard or railroad retirement benefits, no RRB-1099 railroad benefits (including none inside socialSecurityBenefits) and no active-duty military pay; and miQualifyingRetirementBenefits, when sent, is the Form 4884 line 8 column F total as that year's Form 4884 instructions direct. |
| miFilerBirthYearinteger | MI only, with miRetirementFactsAffirmed: the filer's own year of birth. |
| miFilerBornOnJanuary1boolean | MI only: true if the filer was born on January 1 (counted as 67 a year earlier); omitted = false. |
| miSpouseBirthYearinteger | MI only, joint returns with miRetirementFactsAffirmed: the spouse's own year of birth. |
| miSpouseBornOnJanuary1boolean | MI only, joint returns: true if the spouse was born on January 1; omitted = false. |
| miQualifyingRetirementBenefitsnumber | MI only: the Form 4884 line 8 column F total, at most pensionDistributionTaxable. Needed only when Section D could exceed the standard deduction; that return declines without it. |
| miDependentsClaimedinteger | MI only: dependents claimed on the federal return (qualifying children and qualifying relatives), each adding one MI-1040 line 9a exemption. Omitted = 0 (an over-tax). A dependent filer claiming dependents declines. |
curl https://tax-mcp.com/api/mcp/tax-compute/state \
-H "Authorization: Bearer $TAX_MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"state": "mi",
"year": 2025,
"filingStatus": "married_filing_jointly",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 90000,
"medicareWages": 90000,
"taxExemptInterest": 0,
"miDependentsClaimed": 2,
"miNoAdditionsAffirmed": true,
"miFilingStatusMatchesAffirmed": true,
"miNoRetirementOrAgeDeductionsAffirmed": true
}'{
"computed": true,
"state": "mi",
"year": 2025,
"filingStatus": "married_filing_jointly",
"federalAGI": 90000,
"taxableIncome": 66800,
"incomeTax": 2839,
"additionalTaxes": [],
"totalTax": 2839,
"notEvaluated": [
"every credit, nonrefundable and refundable (including the homestead property tax credit and the earned income credit) — over-tax",
"every Schedule 1 subtraction other than taxable Social Security and the retirement deductions below (e.g. U.S. obligation interest, 2026-2028 tips and overtime) — over-tax",
"special exemptions (deaf, blind, disabled, disabled veteran), the stillbirth exemption and a married non-joint filer's spouse exemption (MCL 206.30(2)(a), when the spouse has no gross income and is not another taxpayer's dependent) — over-tax",
"interest on Michigan obligations is added with the rest of taxExemptInterest — over-tax",
"use tax — under-tax when owed",
"city income tax — a separate return, not part of this answer",
"line 10 is federal AGI; the same return rounded otherwise can show a different AGI (not_modeled.cents_rounding), moving the tax by up to the year's rate times the difference plus $1",
"Michigan payments, refund and the filing requirement",
"retirement: with miRetirementFactsAffirmed only the Tier 2 and Tier 3 standard deductions and the 2023-2025 Form 4884 Section D phase-in are computed, for a key person born 1946 or later in 2020-2025; a January 1 birthday counts as 67 a year early only with its flag (otherwise an over-tax or a decline)"
],
"attestationsRelied": [
"miNoAdditionsAffirmed",
"miFilingStatusMatchesAffirmed",
"miNoRetirementOrAgeDeductionsAffirmed"
],
"lines": [
{ "lineId": "MI-1040:10", "label": "Federal adjusted gross income", "amount": 90000 },
{
"lineId": "MI-1040:11",
"label": "Additions (interest on other states' obligations)",
"amount": 0
},
{ "lineId": "MI-1040:12", "label": "Line 10 plus line 11", "amount": 90000 },
{ "lineId": "MI-SCH1:14", "label": "Schedule 1: taxable Social Security", "amount": 0 },
{ "lineId": "MI-1040:13", "label": "Subtractions from Schedule 1", "amount": 0 },
{ "lineId": "MI-1040:14", "label": "Income subject to tax", "amount": 90000 },
{ "lineId": "MI-1040:15", "label": "Exemption allowance", "amount": 23200 },
{ "lineId": "MI-1040:16", "label": "Taxable income", "amount": 66800 },
{ "lineId": "MI-1040:17", "label": "Tax (4.25%)", "amount": 2839 }
],
"flags": [],
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "mi", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "<computation-support notice — see full response>"
}
}Full response, including line derivations
{
"computed": true,
"state": "mi",
"year": 2025,
"filingStatus": "married_filing_jointly",
"federalAGI": 90000,
"taxableIncome": 66800,
"incomeTax": 2839,
"additionalTaxes": [],
"totalTax": 2839,
"notEvaluated": [
"every credit, nonrefundable and refundable (including the homestead property tax credit and the earned income credit) — over-tax",
"every Schedule 1 subtraction other than taxable Social Security and the retirement deductions below (e.g. U.S. obligation interest, 2026-2028 tips and overtime) — over-tax",
"special exemptions (deaf, blind, disabled, disabled veteran), the stillbirth exemption and a married non-joint filer's spouse exemption (MCL 206.30(2)(a), when the spouse has no gross income and is not another taxpayer's dependent) — over-tax",
"interest on Michigan obligations is added with the rest of taxExemptInterest — over-tax",
"use tax — under-tax when owed",
"city income tax — a separate return, not part of this answer",
"line 10 is federal AGI; the same return rounded otherwise can show a different AGI (not_modeled.cents_rounding), moving the tax by up to the year's rate times the difference plus $1",
"Michigan payments, refund and the filing requirement",
"retirement: with miRetirementFactsAffirmed only the Tier 2 and Tier 3 standard deductions and the 2023-2025 Form 4884 Section D phase-in are computed, for a key person born 1946 or later in 2020-2025; a January 1 birthday counts as 67 a year early only with its flag (otherwise an over-tax or a decline)"
],
"attestationsRelied": [
"miNoAdditionsAffirmed",
"miFilingStatusMatchesAffirmed",
"miNoRetirementOrAgeDeductionsAffirmed"
],
"lines": [
{ "lineId": "MI-1040:10", "label": "Federal adjusted gross income", "amount": 90000 },
{
"lineId": "MI-1040:11",
"label": "Additions (interest on other states' obligations)",
"amount": 0
},
{ "lineId": "MI-1040:12", "label": "Line 10 plus line 11", "amount": 90000 },
{ "lineId": "MI-SCH1:14", "label": "Schedule 1: taxable Social Security", "amount": 0 },
{ "lineId": "MI-1040:13", "label": "Subtractions from Schedule 1", "amount": 0 },
{ "lineId": "MI-1040:14", "label": "Income subject to tax", "amount": 90000 },
{ "lineId": "MI-1040:15", "label": "Exemption allowance", "amount": 23200 },
{ "lineId": "MI-1040:16", "label": "Taxable income", "amount": 66800 },
{ "lineId": "MI-1040:17", "label": "Tax (4.25%)", "amount": 2839 }
],
"flags": [],
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "mi", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}
}Responses
| Status | Meaning |
|---|---|
| 200 | Computed return |
| 400 | Invalid body / JSON / failed validation |
| 401 | Missing / unknown / revoked key (no enumeration) |
| 403 | Account suspended — contact billing (distinct from 401: the key is valid) |
| 409 | Idempotency-Key reused with a different body (`idempotency_key_reused`), or a concurrent in-flight duplicate (`idempotency_key_in_progress`). Retry; NOT billed. |
| 429 | Monthly quota exhausted (account-wide;Monthly quota exhausted (account-wide; `quota_exceeded`, next_action `upgrade_plan_or_wait_next_period`, retry_safe false) or per-minute rate exceeded (`rate_limit_exceeded`, next_action `retry_after_backoff`, retry_safe true). Not billed. |
| 500 | Sanitized server error computing the return |
| 503 | Metering outage — fail-closed (the call is NOT silently served free) |
Any other state value is a 400 with reason: "unsupported_state". A CA, NY, IL, NC or MI decline with code federal_declined means the federal return underneath could not be computed. The no-income-tax states need nhInterestDividendsTaxNotOwedAffirmed (NH 2020-2024), tnHallTaxNotOwedAffirmed (TN 2020) or waCapitalGainsExciseNotOwedAffirmed (WA 2022-2026) on every return in those years. See the state guide.
Discovery
GET /api/mcp/tax-compute/statereturns each state's years and modeled facts. It needs a key and uses no quota.