Guide to the Worker Tax Withholdings API

The Worker Tax Withholdings API lets you read and update the income tax withholding elections a worker has made on their federal Form W-4 and on their state withholding forms. These elections determine how much income tax Everee withholds from the worker's pay.

Endpoint	What it manages
Get W-4 tax withholding settings and Update W-4 tax withholding settings	Federal income tax withholding (Form W-4)
Get state tax withholding settings and Update state tax withholding settings	State income tax withholding, for every state in which the worker has withholding settings

Federal and state settings differ

Take care when you reuse code between the two sets of endpoints. They look similar but behave differently:

	Federal (W-4)	State
Path	`/workers/{id}/forms/FED_W4`	`/workers/{id}/forms/state-withholding`
Effective date	Required. Each change takes effect on the date you specify.	Not accepted. Updates apply to the worker's current settings. `GET` accepts an optional `date` and defaults to today.
Extra withholding	`extraWithholdingsMonthly`, a monthly amount	`extraWithholding`, an amount per pay period
Shape	One form per request	A list with one entry per state, updated together
Fields	Fixed by the federal W-4	Vary by state. A state's form may not ask for a filing status or allowances.

State withholding settings

Which states appear

GET returns one entry for each state in which the worker currently has state income tax withholding settings. A worker could have more than one entry, for example if they live in one state and work in another. A worker with no state income tax withholding, for example in a state with no income tax, gets an empty array. Pass state to retrieve just one.

You can only update states that GET returns. Sending a state the worker isn't set up for fails the request.

Fields that don't apply to a state

States collect different information. If a state's form has no filing status question, maritalStatus is null in responses. The same goes for totalAllowances and extraWithholding. Values you send for a field the state doesn't ask about are ignored. exempt is always present, and is false when the state's form has no exemption question.

Updating settings

PUT takes a list of states to update. Keep these rules in mind:

state and exempt are required for each entry. exempt is always saved, so send the worker's current value if you aren't changing it.
Omitted fields keep their current value. If you leave out maritalStatus, totalAllowances or extraWithholding, the worker's existing answer is kept rather than reset. You can send a single state's changes without re-sending everything else.
Each state may appear once. Duplicate states in a single request are rejected.
The request is all-or-nothing. If any state is invalid, no states are updated.
maritalStatus must be a value the state's form accepts. These values vary by state. Read the worker's current settings with GET to see the format.
The response lists the worker's settings for the states you updated, after the change.

Anything a state's form asks for that this API doesn't expose, such as state-specific questions beyond the four fields, is left unchanged.

Example

Update a worker's California settings:

PUT /integration/v1/workers/{id}/forms/state-withholding

{
  "stateWithholdings": [
    {
      "state": "CA",
      "maritalStatus": "S",
      "totalAllowances": 2,
      "extraWithholding": { "amount": "25.00", "currency": "USD" },
      "exempt": false
    }
  ]
}