---
title: "Paycheck-withholding (W-4) checkup"
method: POST
path: "/v1/tax/w4-checkup"
tags: ["Tax"]
---

# Paycheck-withholding (W-4) checkup

`POST /v1/tax/w4-checkup`

## Request

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

Are you on track with federal withholding? Projects the year's federal tax liability (reusing the tax engine) from the embedded tax situation, compares it against what will be withheld at the current pace (year-to-date plus the per-paycheck amount over the remaining pay periods), and reports the expected refund or balance due, the status, and the per-paycheck W-4 adjustment (line 4c) to land on target. Supply the prior year's tax to also check the §6654 safe harbor and flag underpayment-penalty risk. Deterministic; not tax advice.

## Request body

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

## Response `200`

The withholding checkup

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

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)