---
title: "Worker Federal Tax"
method: POST
path: "/workers/{workerId}/federaltax"
tags: ["Worker"]
---

# Worker Federal Tax

`POST /workers/{workerId}/federaltax`

## Request

- Base URL: `https://api.paychex.com`
- URL: `https://api.paychex.com/workers/{workerId}/federaltax`
- Auth: none declared
- TypeScript: <https://skmtc.dev/paychex/apis/external-api/docs/workers/:workerId/federaltax/post.ts> (a function with typed inputs; its response is checked against the schema)

WARNING: This endpoint will be deprecated on 1/30/2026. Until this date, POST federal tax will behave both as a POST and PATCH call accordingly, depending on if the worker already has a federal tax setup.  
NOTE: In-progress workers are created with a federal tax setup automatically. See POST In-progress worker. If a worker does not have a federal tax set up, this endpoint will create one with the values given in the request.

## Path parameters

- `workerId` string, required

## Request body

- WorkerFederalTaxResource: The representational state of the a worker's federal tax setup.
  - `taxId` string: The ID for the federal tax item.
  - `filingStatus` 'SINGLE_OR_MARRIED_FILING_SEPARATELY' | 'MARRIED_FILING_JOINTLY' | 'HEAD_OF_HOUSEHOLD': Filing status.
  - `multipleJobs` 'true' | 'false': See federal W-4 instructions.
  - `dependentsAmount` string: See federal W-4 instructions.
  - `otherIncome` string: See federal W-4 instructions.
  - `deductionsAmount` string: See federal W-4 instructions.
  - `taxesWithheld` 'true' | 'false': Should federal taxes be withheld: true means federal taxes are withheld, false means federal taxes are NOT withheld. Earnings will still be reported to state and federal agencies.
  - `extraWithholdingAmount` string: See federal W-4 instructions. Can be used with extraWithholdingPercentage or overrideWithholdingPercentage. Cannot be used with overrideWithholdingAmount. If extraWithholdingAmount is entered, existing overrideWithholdingAmount data will be removed.
  - `overrideWithholdingAmount` string: See federal W-4 instructions. Cannot be used with extraWithholdingAmount, extraWithholdingPercentage, or overrideWithholdingPercentage. If entered, existing extraWithholdingAmount, extraWithholdingPercentage, and overrideWithholdingPercentage data will be removed.
  - `extraWithholdingPercentage` string: See federal W-4 instructions. Can be used with extraWithholdingAmount. Cannot be used with overrideWithholdingAmount or overrideWithholdingPercentage. If entered, existing overrideWithholdingAmount and overrideWithholdingPercentage data will be removed.
  - `overrideWithholdingPercentage` string: See federal W-4 instructions. Can be used with extraWithholdingAmount. Cannot be used with overrideWithholdingAmount or extraWithholdingPercentage. If entered, existing overrideWithholdingAmount and extraWithholdingPercentage data will be removed.

## Response `201`

Worker Federal Tax successfully added

- object
  - `content` WorkerFederalTaxResource: The representational state of the a worker's federal tax setup.
    - `taxId` string: The ID for the federal tax item.
    - `filingStatus` 'SINGLE_OR_MARRIED_FILING_SEPARATELY' | 'MARRIED_FILING_JOINTLY' | 'HEAD_OF_HOUSEHOLD': Filing status.
    - `multipleJobs` 'true' | 'false': See federal W-4 instructions.
    - `dependentsAmount` string: See federal W-4 instructions.
    - `otherIncome` string: See federal W-4 instructions.
    - `deductionsAmount` string: See federal W-4 instructions.
    - `taxesWithheld` 'true' | 'false': Should federal taxes be withheld: true means federal taxes are withheld, false means federal taxes are NOT withheld. Earnings will still be reported to state and federal agencies.
    - `extraWithholdingAmount` string: See federal W-4 instructions. Can be used with extraWithholdingPercentage or overrideWithholdingPercentage. Cannot be used with overrideWithholdingAmount. If extraWithholdingAmount is entered, existing overrideWithholdingAmount data will be removed.
    - `overrideWithholdingAmount` string: See federal W-4 instructions. Cannot be used with extraWithholdingAmount, extraWithholdingPercentage, or overrideWithholdingPercentage. If entered, existing extraWithholdingAmount, extraWithholdingPercentage, and overrideWithholdingPercentage data will be removed.
    - `extraWithholdingPercentage` string: See federal W-4 instructions. Can be used with extraWithholdingAmount. Cannot be used with overrideWithholdingAmount or overrideWithholdingPercentage. If entered, existing overrideWithholdingAmount and overrideWithholdingPercentage data will be removed.
    - `overrideWithholdingPercentage` string: See federal W-4 instructions. Can be used with extraWithholdingAmount. Cannot be used with overrideWithholdingAmount or extraWithholdingPercentage. If entered, existing overrideWithholdingAmount and extraWithholdingPercentage data will be removed.
  - `links` Link1[]
    - `href` string
    - `hreflang` string
    - `title` string
    - `type` string
    - `deprecation` string
    - `profile` string
    - `name` string
    - `templated` boolean

## Other responses

- `400`: Invalid resource or field,The request cannot be performed since the worker is in a state which does not allow this action(API-19)
- `404`: Worker not found
- `500`: Internal Server Error

---

[API](https://skmtc.dev/paychex/apis/external-api.md) - [All operations](https://skmtc.dev/paychex/apis/external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paychex/apis/external-api/revisions/07161d3e073f?raw)