---
title: "Federal Withholding Calculator (Percentage Method)"
method: POST
path: "/v1/tools/compute_federal_withholding"
tags: ["TODO_TAGS_REVIEW", "TODO_AP2_EXPORT_REVIEW"]
---

# Federal Withholding Calculator (Percentage Method)

`POST /v1/tools/compute_federal_withholding`

## Request

- Base URL: `https://ainumbers.co`
- URL: `https://ainumbers.co/v1/tools/compute_federal_withholding`
- Auth: none declared

Federal income tax withholding via the IRS Publication 15-T percentage method, Worksheet 1A, for a 2020-or-later Form W-4. tax_year is a required input and selects the edition: the 2026 Section 1 and 2025 Section 4 STANDARD Withholding Rate Schedules are both carried, and an absent or unsupported year fails closed with error unsupported_or_missing_tax_year rather than defaulting to an edition the caller never chose. Supports single/MFS, married filing jointly, and head of household, plus Step 3 dependents credit, Step 4(a) other income, Step 4(b) deductions, and Step 4(c) extra withholding. STANDARD Withholding Rate Schedules only; the Form W-4 Step 2 multiple-jobs checkbox table is out of scope. Federal only, not tax advice, state withholding out of scope. Feeds art-339-compute-gross-to-net as its federal_withholding_per_period input, which must be called with the same tax_year. Not compute_gross_to_net itself, which computes FICA and net pay.

**Tool URL:** https://ainumbers.co/chaingraph/art-338-compute-federal-withholding.html

## Request body

- object
  - `filing_status` unknown, required
  - `gross_wages_per_period` number
  - `pay_frequency` unknown, required
  - `step3_dependents_credit_annual` number
  - `step4a_other_income_annual` number
  - `step4b_deductions_annual` number
  - `step4c_extra_withholding_per_period` number
  - `tax_year` unknown, required

## Response `200`

Successful tool execution result

- object
  - `adjusted_annual_wage_amount` integer
  - `bracket_at_least` integer
  - `bracket_rate` number
  - `constants_version` string
  - `error` string
  - `federal_withholding_per_period` number
  - `filing_status` string
  - `note` string
  - `pay_frequency` string
  - `periods_per_year` integer
  - `regulatory_basis` string
  - `step3_credit_this_period` integer
  - `step4c_extra_withholding_per_period` integer
  - `supported_tax_years` string[]
  - `tax_year` string
  - `tentative_annual_withholding` integer
  - `tentative_withholding_this_period` number

---

[API](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite.md) · [All operations](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite/llms.txt) · [OpenAPI document](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite/revisions/b462e4f5bb28?raw)