PApaychex
Worker

Worker Federal Tax

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.

post/workers/{workerId}/federaltax

Request

Path parameters

workerIdstring required

ID associated with desired worker.

Request body

taxIdstring

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.

dependentsAmountstring

See federal W-4 instructions.

otherIncomestring

See federal W-4 instructions.

deductionsAmountstring

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.

extraWithholdingAmountstring

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.

overrideWithholdingAmountstring

See federal W-4 instructions. Cannot be used with extraWithholdingAmount, extraWithholdingPercentage, or overrideWithholdingPercentage. If entered, existing extraWithholdingAmount, extraWithholdingPercentage, and overrideWithholdingPercentage data will be removed.

extraWithholdingPercentagestring

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.

overrideWithholdingPercentagestring

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.

Example request

{
  "taxId": "3520000118851387",
  "filingStatus": "MARRIED_FILING_JOINTLY",
  "multipleJobs": "false",
  "dependentsAmount": "123.45",
  "otherIncome": "23.45",
  "deductionsAmount": "2.45",
  "taxesWithheld": "true",
  "extraWithholdingAmount": "3.45",
  "overrideWithholdingAmount": "9.45",
  "extraWithholdingPercentage": "19.45",
  "overrideWithholdingPercentage": "31.95"
}

Response

Worker Federal Tax successfully added

Example response

{
  "content": {
    "taxId": "3520000118851387",
    "filingStatus": "MARRIED_FILING_JOINTLY",
    "multipleJobs": "false",
    "dependentsAmount": "123.45",
    "otherIncome": "23.45",
    "deductionsAmount": "2.45",
    "taxesWithheld": "true",
    "extraWithholdingAmount": "3.45",
    "overrideWithholdingAmount": "9.45",
    "extraWithholdingPercentage": "19.45",
    "overrideWithholdingPercentage": "31.95"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.