---
title: "Update federal taxes for an employee"
method: PUT
path: "/v1/employees/{employee_uuid}/federal_taxes"
tags: ["Employee Tax Setup"]
---

# Update federal taxes for an employee

`PUT /v1/employees/{employee_uuid}/federal_taxes`

Updates federal tax (W4) information for an employee. Only rev_2020_w4 format is accepted for updates.

scope: `employee_federal_taxes:write`

## Path parameters

- `employee_uuid` string, required

## Headers

- `X-Gusto-API-Version` '2026-06-15'

## Request body

- object
  - `version` string, required — The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer) for information on how to use this field.
  - `w4_data_type` 'rev_2020_w4', required — The version of the W4 form. Only rev_2020_w4 is accepted for updates.
  - `filing_status` 'Single' | 'Married' | 'Head of Household' | 'Exempt from withholding', required — Determines which tax return form an individual will use. One of: Single, Married, Head of Household, Exempt from withholding.
  - `two_jobs` boolean — If there are only two jobs (e.g., you and your spouse each have a job), set to true.
  - `dependents_amount` number — Amount for dependents; a dependent entitles the taxpayer to claim a dependency exemption.
  - `other_income` number — Other income amount.
  - `deductions` number — Deductions other than the standard deduction to reduce withholding.
  - `extra_withholding` number — Additional amount to be withheld from each paycheck.
  - `federal_withholding_allowance` integer — Only applicable when w4_data_type is 'pre_2020_w4' (pre-2020 W4 forms are deprecated for updates).
  - `additional_withholding` number — Only applicable when w4_data_type is 'pre_2020_w4' (pre-2020 W4 forms are deprecated for updates).

## Response `200`

Successful

- union — Federal tax information for an employee. The response structure varies based on the w4_data_type field.
  - object — Federal tax information for employees using the pre-2020 W4 form.
    - `version` string, required — The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field.
    - `employee_uuid` string — The UUID of the employee.
    - `employee_id` integer — The internal ID of the employee.
    - `company_id` integer — The internal ID of the company.
    - `w4_data_type` 'pre_2020_w4', required — The version of w4 form.
    - `filing_status` string, nullable — It determines which tax return form an individual will use and is an important factor in computing taxable income. One of: - Single - Married - Head of Household - Exempt from withholding - Married, but withhold as Single
    - `federal_withholding_allowance` number, nullable — An exemption from paying a certain amount of income tax. May be null when filing_status is "Exempt from withholding".
    - `additional_withholding` string, required — An additional withholding dollar amount.
  - object — Federal tax information for employees using the revised 2020 W4 form.
    - `version` string, required — The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field.
    - `employee_uuid` string — The UUID of the employee.
    - `employee_id` integer — The internal ID of the employee.
    - `company_id` integer — The internal ID of the company.
    - `w4_data_type` 'rev_2020_w4', required — The version of w4 form.
    - `filing_status` string, nullable, required — It determines which tax return form an individual will use and is an important factor in computing taxable income. One of: - Single - Married - Head of Household - Exempt from withholding
    - `extra_withholding` string, nullable, required — An employee can request an additional amount to be withheld from each paycheck.
    - `two_jobs` boolean, nullable, required — If there are only two jobs (i.e., you and your spouse each have a job, or you have two), you can set it to true.
    - `dependents_amount` string, nullable, required — A dependent is a person other than the taxpayer or spouse who entitles the taxpayer to claim a dependency exemption.
    - `other_income` string, nullable, required — Other income amount.
    - `deductions` string, nullable, required — Deductions other than the standard deduction to reduce withholding.

## Other responses

- `404` — Not Found The requested resource does not exist. Make sure the provided UUID is valid.
- `409` — Conflict
- `422` — Unprocessable Entity This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

---

[API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)