Guides
  1. Quick Start

Employee Tax Setup

Every employee has a set of federal and state tax parameters that must be filled in before payroll can run correctly for them — things like their W-4 filing status, allowances, extra withholding, and exemption flags. Use these two endpoints to read that tax setup and to fill in or change individual parameters.

This section covers employee-level tax setup. For the company-level equivalent — FEIN, state tax account numbers, SUTA rates — see Company Tax Setup.

Get Employee Tax Setup

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}/taxsetup

Requires a bearer access token (see How to Get API Access). CLIENT_ID is the company identifier returned as id when you create the company. EMPLOYEE_ID is the employee identifier returned as id when you create the employee.

Returns the employee's full tax setup: federal, then one entry per state the employee has tax exposure in (their state of residence, and any additional state they work in). This mirrors the shape of company tax setup, with two differences:

  • There's no suta array. State unemployment insurance is registered and rated at the company level, not per employee.
  • Groups have no ein field. Employees don't have their own federal or state tax account numbers.

Local taxes (for example, New York City's or Yonkers') don't get their own top-level group. Their parameters — Total Allowances - NYC, Additional Withholding - NYC, Additional Withholding - Yonkers — appear inside the parameters array of the relevant state's entry, alongside that state's own income tax parameters.

Reading the response

Top-level fields:

FieldTypeDescription
effectiveFromstring (ISO date)The effective date of this tax setup.
isCompletebooleantrue only when federal and every entry in state are complete.
federalobjectFederal tax setup. See "Group fields" below.
statearray of objectsState income tax and related state/local payroll tax setup (including any city taxes, like NYC's or Yonkers'). One entry per state the employee has tax exposure in. See "Group fields" below.

Group fields (on federal, and on each entry in state):

FieldTypeDescription
namestringHuman-readable name of this tax group, e.g. "State Tax Setup - NY".
statestringTwo-letter state code. Present on state entries only, not on federal.
isCompletebooleantrue when every required parameter (isOptional: false) in this group has a value.
parametersarray of objectsThe individual tax parameters for this group. See "Parameter fields" below.

Parameter fields (on each entry in parameters):

FieldTypeDescription
taxIdstringOpaque identifier for this specific parameter. Pass it back in the update call (below) to set this parameter's value. Specific to this employee — don't reuse it for another employee.
compatibleStatesarray of stringsStates this parameter also applies to. ["FED"] marks a federal-only parameter; ["ALL"] means it applies regardless of state. Unlike company tax setup, this is present on every parameter here.
parameterTypeintegerControls how value should be interpreted. See "Parameter type values" below.
namestringInternal field name, e.g. FILINGSTATUS, _ADDITIONALWH. The same internal name can be reused across different taxes — for example, _IS_EXEMPT_EE_BY_EE appears once per tax the employee can be exempted from, each with its own taxId and caption. Always key off taxId, never name.
captionstringHuman-readable label, e.g. "Additional Withholding - NYC".
hintstringHelp text for the parameter, often pointing to the relevant W-4 line (e.g. "W-4, step 4, box 4(c)"). Empty string if there isn't any.
valuestringThe parameter's current value. Only present once the parameter has been set for this employee — the field is omitted entirely otherwise, rather than appearing as an empty string.
defaultValuestringDefault value for the parameter, if any. Not every parameter has one.
isOptionalbooleanWhether this parameter is required for the group's isComplete to be true.
optionsarray of objectsPresent only on parameters with a fixed set of choices (parameterType 5, and some parameterType 1 parameters). Each entry is { caption, description, value } — pass the value of the chosen option as the update payload's value.
regExstringPresent only on parameters with format validation (e.g. currency, whole-number allowances). The value must match this pattern.
warningstringPresent alongside regEx. Message describing the expected format, for display if validation fails.
isEditableOnlyByAdminbooleanPresent on some parameters.
isVisibleOnlyByAdminbooleanPresent on some parameters.

Parameter type values:

ValueMeaning
1Boolean (true/false). Sometimes paired with options giving explicit labels for the two values instead of a plain checkbox.
3Currency amount. Has a regEx restricting it to a dollar amount with up to 2 decimal places.
4Percentage. Has a regEx restricting it to a numeric percentage.
5Select — choose one value from options.
6Free text — though a regEx may still restrict its format, as with the whole-number allowance fields below.

These are the values seen in example responses; treat any parameterType not listed here as unrecognized rather than guessing at its format, and check regEx/options/hint for formatting clues.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const EMPLOYEE_ID = process.env.EMPLOYEE_ID;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/employees/${EMPLOYEE_ID}/taxsetup`;

async function getEmployeeTaxSetup() {
  const response = await fetch(url, {
    method: "GET",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
  });

  console.log(response.status);
  console.log(await response.text());
}

getEmployeeTaxSetup();
curl -s -X GET "https://api.worklio.com/wep/companies/$CLIENT_ID/employees/$EMPLOYEE_ID/taxsetup" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -H "x-api-version: 2.0" | jq .

Example response

This example is for an employee living and working in New York — that's why the only state entry is NY. An employee with exposure in more states would have one entry per state.

{
  "effectiveFrom": "2026-09-11",
  "isComplete": false,
  "federal": {
    "name": "Federal Tax Setup",
    "isComplete": true,
    "parameters": [
      {
        "taxId": "soBXw71H0qU0INeV_JRz0wcMp5m7bAkngWqwvIkNP-QLN8W6McpzcGQ@@",
        "compatibleStates": ["FED"],
        "parameterType": 5,
        "name": "FILINGSTATUS",
        "caption": "Filing Status",
        "hint": "Please select filling status of employee from W-4, step 1, box (c).",
        "defaultValue": "S",
        "isOptional": false,
        "options": [
          { "caption": "Single or Married filing separately", "description": "", "value": "S" },
          { "caption": "Married filing jointly or Qualifying surviving spouse", "description": "", "value": "M" },
          { "caption": "Head of household", "description": "", "value": "H" },
          { "caption": "Non-Resident Alien", "description": "", "value": "NRA" }
        ]
      },
      {
        "taxId": "AVxescmJpyMLAGKtqzlBy4ly9LjRBTecc1PdvkWeczwH-Wn6WnLiYuTM@",
        "compatibleStates": ["FED"],
        "parameterType": 3,
        "name": "NRA_EXEMPTION_AMT",
        "caption": "NRA Exemption Amount",
        "hint": "Use this parameter for nonresident alien employees that have filled out IRS Form 8233 and are exempt from a portion of wages earned. For example, if an employee's first $5,000 earned is exempt, you would set the parameter to 5000.",
        "defaultValue": "0.0",
        "isOptional": false,
        "regEx": "^([0-9]+([.][0-9]{0,2})?)$",
        "warning": "Please enter valid ($) amount with up to 2 decimal places"
      },
      {
        "taxId": "0LI1-mZgk50Fkstm5gfoOkxzo-0x902d3uzbNTMftZprFSfz-gTvBng@@",
        "compatibleStates": ["FED"],
        "parameterType": 1,
        "name": "TWO_JOBS",
        "caption": "Two Jobs",
        "hint": "Please select this box according to employees selection in W-4, step 2, box (c).",
        "defaultValue": "FALSE",
        "isOptional": false,
        "options": [
          { "caption": "0", "description": "", "value": "FALSE" },
          { "caption": "1", "description": "", "value": "TRUE" }
        ]
      },
      {
        "taxId": "MnAFb8hSPPypfarwD3aFLkG2CxwT7WGCIhb6YtyKPA__zSXjReWCxKA@@",
        "compatibleStates": ["FED"],
        "parameterType": 3,
        "name": "DEPENDENTS_AMT",
        "caption": "Claim Dependents",
        "hint": "Enter a total dollar amount employee claimed for dependents in W-4, step 3, box 3.",
        "isOptional": true,
        "regEx": "^([0-9]+([.][0-9]{0,2})?)$",
        "warning": "Please enter valid ($) amount with up to 2 decimal places"
      },
      {
        "taxId": "ee_f_YPRPnNF0DuBCM77HCOP0DtS1VAsIuXg0UMzd3D7ua94AV_5KuT4@",
        "compatibleStates": ["FED"],
        "parameterType": 3,
        "name": "OTHER_INCOME",
        "caption": "Other Income",
        "hint": "Enter a dollar amount employee entered in W-4, Step 4, box 4(a).",
        "isOptional": true,
        "regEx": "^([0-9]+([.][0-9]{0,2})?)$",
        "warning": "Please enter valid ($) amount with up to 2 decimal places"
      },
      {
        "taxId": "3184N8g1bj4Kktu8qn1Pa71Zv2XxsoC7aScnseobESfz-gTLShg74xWg@",
        "compatibleStates": ["FED"],
        "parameterType": 3,
        "name": "DEDUCTIONS",
        "caption": "Deductions",
        "hint": "Enter a dollar amount employee entered in W-4, Step 4, box 4(b).",
        "isOptional": true,
        "regEx": "^([0-9]+([.][0-9]{0,2})?)$",
        "warning": "Please enter valid ($) amount with up to 2 decimal places"
      },
      {
        "taxId": "kx85lJPJmOvDxPLniFoGVSgoBqHswTs_DxTjvd8ECV_5DqiYxRE_wEdU@",
        "compatibleStates": [],
        "parameterType": 3,
        "name": "_FEDADDITIONALWH2",
        "caption": "Extra Withholding",
        "hint": "Enter a dollar amount employee entered in W-4, step 4, box 4(c).",
        "isOptional": true,
        "regEx": "^([0-9]+([.][0-9]{0,2})?)$",
        "warning": "Please enter valid ($) amount with up to 2 decimal places"
      },
      {
        "taxId": "3184N8g1bjoKltu8qn1Pa71Zv2XxsoC7aScnuZZ_ASfz-gTLSjx3p",
        "compatibleStates": ["ALL"],
        "parameterType": 1,
        "name": "_IS_EXEMPT_EE_BY_EE",
        "caption": "Exempt From Federal Income Tax",
        "hint": "Please specify whether employee is exempt from this tax",
        "isOptional": false,
        "options": [
          { "caption": "0", "description": "", "value": "false" },
          { "caption": "1", "description": "", "value": "true" }
        ]
      },
      {
        "taxId": "FDtDR0GnLc8AccbtCunYUWFDuCsj0bJJsjMkC_V56lpy4kaorhhDn",
        "compatibleStates": ["ALL"],
        "parameterType": 1,
        "name": "_IS_EXEMPT_EE_BY_EE",
        "caption": "Exempt From Social Security",
        "hint": "Please specify whether employee is exempt from this tax",
        "isOptional": false,
        "options": [
          { "caption": "0", "description": "", "value": "false" },
          { "caption": "1", "description": "", "value": "true" }
        ]
      },
      {
        "taxId": "i4WuJwz4NvV06zacV7LMjza9BHROlfCtSyNvePOxp3gBX_kOqLyJc",
        "compatibleStates": ["ALL"],
        "parameterType": 1,
        "name": "_IS_EXEMPT_EE_BY_ER",
        "caption": "Exempt From Federal Unemployment Tax",
        "hint": "Please specify whether employee is exempt from this tax",
        "isOptional": false,
        "isEditableOnlyByAdmin": true,
        "isVisibleOnlyByAdmin": true,
        "options": [
          { "caption": "0", "description": "", "value": "false" },
          { "caption": "1", "description": "", "value": "true" }
        ]
      },
      {
        "taxId": "i4WuJwz4NvV0xxqcV7LMjza9BHROlfCtSyNvfPeht3gBX_kOqLyJc",
        "compatibleStates": ["ALL"],
        "parameterType": 1,
        "name": "_IS_EXEMPT_EE_BY_EE",
        "caption": "Exempt From Medicare",
        "hint": "Please specify whether employee is exempt from this tax",
        "isOptional": false,
        "options": [
          { "caption": "0", "description": "", "value": "false" },
          { "caption": "1", "description": "", "value": "true" }
        ]
      }
    ]
  },
  "state": [
    {
      "name": "State Tax Setup - NY",
      "state": "NY",
      "isComplete": false,
      "parameters": [
        {
          "taxId": "dlDj6_zuGc5rcQG2kU3PL_gvr6wPUskgLD6Z8KU_R3d8m6GveAFf3ULI@",
          "compatibleStates": ["NE", "NM", "MN", "ID", "KS", "UT", "WI", "ND", "DE", "MT", "CO", "MD", "AS", "GU", "VI", "MP", "OR", "NY"],
          "parameterType": 5,
          "name": "FILINGSTATUS",
          "caption": "Filing Status",
          "hint": "Please select filling status of employee",
          "defaultValue": "S",
          "isOptional": false,
          "options": [
            { "caption": "Single", "description": "", "value": "S" },
            { "caption": "Married", "description": "", "value": "M" },
            { "caption": "Married but use single rate", "description": "", "value": "MH" }
          ]
        },
        {
          "taxId": "6vFtymsudiLE2rEb-4xldzWZ-qjXBUtHzf5zCTvz-girUhg7x1nnmkg@@",
          "compatibleStates": ["NY", "NJ", "NC", "GA", "NE", "NM", "MN", "SC", "KY", "AR", "HI", "ID", "IA", "KS", "ME", "UT", "VT", "VA", "WI", "DC", "ND", "OK", "DE", "MO", "MT", "RI", "CO", "MD", "MI", "WV", "AS", "GU", "VI", "MA", "MP", "OH", "OR", "CA"],
          "parameterType": 6,
          "name": "TOTALALLOWANCES",
          "caption": "Total Allowances",
          "hint": "Please enter the total number of allowances",
          "defaultValue": "0",
          "isOptional": false,
          "regEx": "^([0-9]+)$",
          "warning": "Please enter positive integer"
        },
        {
          "taxId": "8PJeQtMaPMpQZ27ZIaIFcdb0nzFXK73iE3E_09oEy0Z4I8dZw9YOUFw@@",
          "compatibleStates": ["NY"],
          "parameterType": 6,
          "name": "TOTALALLOWANCESNYC",
          "caption": "Total Allowances - NYC",
          "hint": "Please enter the total number of allowances for New York City tax",
          "defaultValue": "0",
          "isOptional": false,
          "regEx": "^([0-9]+)$",
          "warning": "Please enter positive integer"
        },
        {
          "taxId": "91J20nf0Olhjh0wx5wSlMvi_TWMroZITbUPr6hTLShRb31nD1io4cyg@@",
          "compatibleStates": ["AZ", "NY", "NJ", "NC", "GA", "CA", "NE", "NM", "IL", "MN", "SC", "KY", "AR", "PA", "HI", "ID", "IA", "KS", "ME", "UT", "VT", "VA", "WI", "CT", "DC", "ND", "OK", "DE", "MO", "MS", "MT", "RI", "AL", "CO", "MD", "MI", "WV", "AS", "GU", "IN", "PR", "VI", "MA", "MP", "OH", "OR"],
          "parameterType": 3,
          "name": "_ADDITIONALWH",
          "caption": "Additional Withholding",
          "hint": "Please enter any additional ($) amount employee wants to withhold each pay period for state tax.",
          "defaultValue": "0.00",
          "isOptional": false,
          "regEx": "^([0-9]+([.][0-9]{0,2})?)$",
          "warning": "Please enter valid ($) amount with up to 2 decimal places"
        },
        {
          "taxId": "Tc0VD9VXo6HWXV9DOEa5_YomLsJSvKZEd5vVAcdF5aro2xFDP7W-J3Q@@",
          "compatibleStates": ["NY"],
          "parameterType": 3,
          "name": "ADDITIONALWH-NYC",
          "caption": "Additional Withholding - NYC",
          "hint": "Please enter any additional ($) amount employee wants to withhold each pay period for New York City tax.",
          "defaultValue": "0.00",
          "isOptional": false,
          "regEx": "^([0-9]+([.][0-9]{0,2})?)$",
          "warning": "Please enter valid ($) amount with up to 2 decimal places"
        },
        {
          "taxId": "VDfgOwaZLlW2K6kT_Si6zgKeGoi6KAeHtUH7QZWmiMMdIye1mmsVA7-Y@",
          "compatibleStates": ["NY"],
          "parameterType": 3,
          "name": "ADDITIONALWH-YONKERS",
          "caption": "Additional Withholding - Yonkers",
          "hint": "Please enter any additional ($) amount employee wants to withhold each pay period for Yonkers City tax.",
          "defaultValue": "0.00",
          "isOptional": false,
          "regEx": "^([0-9]+([.][0-9]{0,2})?)$",
          "warning": "Please enter valid ($) amount with up to 2 decimal places"
        },
        {
          "taxId": "1znOZw1bbQW2Dvf2QunuqH-DkQX3Ue3e8KcJR0Ptumd1Q4fyCKtSGDvHWeeaS",
          "compatibleStates": ["NY"],
          "parameterType": 5,
          "name": "_COVERED_EE_ZONE",
          "caption": "MCTMT Covered Employee Zone - New York MCTMT Employer Payroll Tax - Zone 1",
          "hint": "If the employee is a 'covered employee' for MCTMT, please select the zone the payroll expense for this employee is attributable to. The field name contains the phrase Zone 1 but the value applies to the entire tax (the name is generated automatically from a variable referring to the database tag and is misleading). Zone 1 includes the counties of New York (Manhattan), Bronx, Kings (Brooklyn), Queens and Richmond (Staten Island). Zone 2 includes the counties of Rockland, Nassau, Suffolk, Orange, Putnam, Dutchess and Westchester.",
          "isOptional": false,
          "isEditableOnlyByAdmin": true,
          "options": [
            { "caption": "Zone 1", "description": "", "value": "1" },
            { "caption": "Zone 2", "description": "", "value": "2" },
            { "caption": "Not covered", "description": "", "value": "3" }
          ]
        },
        {
          "taxId": "Hn90y4jz7GUjjZO8nIRRq5R3a-WuJcIvRGPhZYJacuJKyLY8D__NAa8k@",
          "compatibleStates": ["AZ", "FL", "NY", "NJ", "TX", "NC", "GA", "CA", "NE", "NV", "NH", "NM", "IL", "MN", "TN", "SC", "KY", "AK", "SD", "WY", "AR", "PA", "HI", "ID", "IA", "KS", "ME", "UT", "VT", "VA", "WI", "CT", "DC", "LA", "ND", "OK", "DE", "MO", "MS", "MT", "RI", "AL", "CO", "MD", "MI", "WV", "AS", "GU", "IN", "PR", "VI", "MA", "MP", "OH", "OR"],
          "parameterType": 1,
          "name": "_HAS_NON_RES_CERT",
          "caption": "Nonresident Certificate",
          "hint": "Please select if employee has nonresident certificate for this state",
          "isOptional": false,
          "options": [
            { "caption": "0", "description": "", "value": "FALSE" },
            { "caption": "1", "description": "", "value": "TRUE" }
          ]
        },
        {
          "taxId": "0LI1-mZgk5ElptNm5gfoOkxzo-0x902d3uzbGUsz1fYbESuT4gTLShgfizg@@",
          "compatibleStates": ["ALL"],
          "parameterType": 1,
          "name": "_IS_EXEMPT_EE_BY_ER",
          "caption": "Exempt From New York State Unemployment Tax",
          "hint": "Please specify whether employee is exempt from this tax",
          "isOptional": false,
          "isEditableOnlyByAdmin": true,
          "isVisibleOnlyByAdmin": true,
          "options": [
            { "caption": "0", "description": "", "value": "false" },
            { "caption": "1", "description": "", "value": "true" }
          ]
        },
        {
          "taxId": "8PJeQtMaPMZwQ2bZIaIFcdb0nzFXK73iE3E___YIqyZ8K8s529YqHD9t2ZA@@",
          "compatibleStates": ["ALL"],
          "parameterType": 1,
          "name": "_IS_EXEMPT_EE_BY_EE",
          "caption": "Exempt From New York State Tax",
          "hint": "Please specify whether employee is exempt from this tax",
          "isOptional": false,
          "options": [
            { "caption": "0", "description": "", "value": "false" },
            { "caption": "1", "description": "", "value": "true" }
          ]
        },
        {
          "taxId": "FDtDR0GnLcc0Rc7tCunYUWFDuCsj0bJJsjMkD_FlmjYK7krItjwP_80BryQ@@",
          "compatibleStates": ["ALL"],
          "parameterType": 1,
          "name": "_IS_EXEMPT_EE_BY_ER",
          "caption": "Exempt From New York SDI",
          "hint": "Please specify whether employee is exempt from this tax",
          "isOptional": false,
          "isEditableOnlyByAdmin": true,
          "isVisibleOnlyByAdmin": true,
          "options": [
            { "caption": "0", "description": "", "value": "false" },
            { "caption": "1", "description": "", "value": "true" }
          ]
        },
        {
          "taxId": "JfO9n0ldy5FC4AXRFX6kn0e55hHeQzR_gQ3iVn7uJsTOKAOf1SXjReWCxKA@@",
          "compatibleStates": ["ALL"],
          "parameterType": 1,
          "name": "_IS_EXEMPT_EE_BY_EE",
          "caption": "Exempt From New York Family Leave Benefits",
          "hint": "Please specify whether employee is exempt from this tax",
          "isOptional": false,
          "options": [
            { "caption": "0", "description": "", "value": "false" },
            { "caption": "1", "description": "", "value": "true" }
          ]
        },
        {
          "taxId": "VDfgOwaZLlmGI50T_Si6zgKeGoi6KAeHtUH7Te2q6K95XzPVgmsVJ_PeSKg@@",
          "compatibleStates": ["ALL"],
          "parameterType": 1,
          "name": "_IS_EXEMPT_EE_BY_ER",
          "caption": "Exempt From New York Employer Compensation Expense Tax",
          "hint": "Please specify whether employee is exempt from this tax",
          "isOptional": false,
          "isEditableOnlyByAdmin": true,
          "isVisibleOnlyByAdmin": true,
          "options": [
            { "caption": "0", "description": "", "value": "false" },
            { "caption": "1", "description": "", "value": "true" }
          ]
        },
        {
          "taxId": "1znOZw1bbT2yJuP2QunuqH-DkQX3Ue3e8KcJTzO5-hd1I_-aHMtKPHe7Jbe2IjhzK",
          "compatibleStates": ["ALL"],
          "parameterType": 1,
          "name": "_IS_EXEMPT_EE_BY_EE",
          "caption": "Exempt From New York City Tax",
          "hint": "Please specify whether employee is exempt from this tax",
          "isOptional": false,
          "options": [
            { "caption": "0", "description": "", "value": "false" },
            { "caption": "1", "description": "", "value": "true" }
          ]
        }
      ]
    }
  ]
}
🚧

FILINGSTATUS appears in both federal and the state entry, as two separate parameters with two separate taxIds and two separate sets of options (federal includes a "NRA" option that NY's doesn't). Set both if the employee needs a filing status for each.

Update Employee Tax Setup

POST https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}/taxsetup

Requires a bearer access token (see How to Get API Access). CLIENT_ID is the company identifier returned as id when you create the company. EMPLOYEE_ID is the employee identifier returned as id when you create the employee.

Sets the value of one or more tax parameters. This is a targeted update, not a full replacement of the employee's tax setup — send only the parameters you're changing; every other parameter keeps its current value.

Request body:

The request body is a JSON array. Each entry sets one parameter:

FieldTypeRequiredDescription
taxIdstringYesThe parameter's taxId, from a Get Employee Tax Setup response.
valuestringYesThe new value. If the parameter had a regEx in the GET response, value must match it. If it had options, value must be one of the listed option values.

Example request

This example fills in the parameters needed to complete the employee's federal and NY state/local tax setup shown above: federal filing status, NY filing status, total allowances (general and NYC), additional withholding (state, NYC, and Yonkers), MCTMT covered employee zone, and the NYC tax exemption flag.

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const EMPLOYEE_ID = process.env.EMPLOYEE_ID;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/employees/${EMPLOYEE_ID}/taxsetup`;

const payload = [
  {
    taxId: "soBXw71H0qU0INeV_JRz0wcMp5m7bAkngWqwvIkNP-QLN8W6McpzcGQ@@", // Filing Status (federal, W-4)
    value: "S"
  },
  {
    taxId: "dlDj6_zuGc5rcQG2kU3PL_gvr6wPUskgLD6Z8KU_R3d8m6GveAFf3ULI@", // Filing Status (NY state)
    value: "S"
  },
  {
    taxId: "6vFtymsudiLE2rEb-4xldzWZ-qjXBUtHzf5zCTvz-girUhg7x1nnmkg@@", // Total Allowances
    value: "100"
  },
  {
    taxId: "8PJeQtMaPMpQZ27ZIaIFcdb0nzFXK73iE3E_09oEy0Z4I8dZw9YOUFw@@", // Total Allowances - NYC
    value: "100"
  },
  {
    taxId: "91J20nf0Olhjh0wx5wSlMvi_TWMroZITbUPr6hTLShRb31nD1io4cyg@@", // Additional Withholding
    value: "5"
  },
  {
    taxId: "Tc0VD9VXo6HWXV9DOEa5_YomLsJSvKZEd5vVAcdF5aro2xFDP7W-J3Q@@", // Additional Withholding - NYC
    value: "15.50"
  },
  {
    taxId: "VDfgOwaZLlW2K6kT_Si6zgKeGoi6KAeHtUH7QZWmiMMdIye1mmsVA7-Y@", // Additional Withholding - Yonkers
    value: "1.5"
  },
  {
    taxId: "1znOZw1bbQW2Dvf2QunuqH-DkQX3Ue3e8KcJR0Ptumd1Q4fyCKtSGDvHWeeaS", // MCTMT Covered Employee Zone - Zone 1
    value: "1"
  },
  {
    taxId: "1znOZw1bbT2yJuP2QunuqH-DkQX3Ue3e8KcJTzO5-hd1I_-aHMtKPHe7Jbe2IjhzK", // Exempt From New York City Tax
    value: "true"
  }
];

async function updateEmployeeTaxSetup() {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });

  console.log(response.status); // 204 on success
}

updateEmployeeTaxSetup();
curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/employees/$EMPLOYEE_ID/taxsetup" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -H "x-api-version: 2.0" \
  -d '[
    { "taxId": "soBXw71H0qU0INeV_JRz0wcMp5m7bAkngWqwvIkNP-QLN8W6McpzcGQ@@", "value": "S" },
    { "taxId": "dlDj6_zuGc5rcQG2kU3PL_gvr6wPUskgLD6Z8KU_R3d8m6GveAFf3ULI@", "value": "S" },
    { "taxId": "6vFtymsudiLE2rEb-4xldzWZ-qjXBUtHzf5zCTvz-girUhg7x1nnmkg@@", "value": "100" },
    { "taxId": "8PJeQtMaPMpQZ27ZIaIFcdb0nzFXK73iE3E_09oEy0Z4I8dZw9YOUFw@@", "value": "100" },
    { "taxId": "91J20nf0Olhjh0wx5wSlMvi_TWMroZITbUPr6hTLShRb31nD1io4cyg@@", "value": "5" },
    { "taxId": "Tc0VD9VXo6HWXV9DOEa5_YomLsJSvKZEd5vVAcdF5aro2xFDP7W-J3Q@@", "value": "15.50" },
    { "taxId": "VDfgOwaZLlW2K6kT_Si6zgKeGoi6KAeHtUH7QZWmiMMdIye1mmsVA7-Y@", "value": "1.5" },
    { "taxId": "1znOZw1bbQW2Dvf2QunuqH-DkQX3Ue3e8KcJR0Ptumd1Q4fyCKtSGDvHWeeaS", "value": "1" },
    { "taxId": "1znOZw1bbT2yJuP2QunuqH-DkQX3Ue3e8KcJTzO5-hd1I_-aHMtKPHe7Jbe2IjhzK", "value": "true" }
  ]'

Example response

204 No Content

Success returns an empty body. There's no confirmation payload — if you need to see the updated values, call Get Employee Tax Setup again.

Error response

If you leave a required parameter unset — for any state the employee has tax exposure in, or federal — the update fails with a 400 and a message listing every parameter still missing a value, by caption:

{
  "status": 0,
  "code": "400",
  "errorCode": "WEP_BadRequest",
  "message": "9/18/2026 - 7:57:40 AM : Filing Status: Value_Required\nAdditional Withholding: Value_Required\nTotal Allowances: Value_Required\nTotal Allowances - NYC: Value_Required\nAdditional Withholding - NYC: Value_Required\nAdditional Withholding - Yonkers: Value_Required\nFiling Status: Value_Required\nMCTMT Covered Employee Zone- New York MCTMT Employer Payroll Tax - Zone 1: Value_Required",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}
🚧

Read taxId values fresh from a GET response before sending an update. They're specific to each employee's tax setup — don't cache or hardcode them, and don't reuse a taxId from one employee for another.

Updated 29 minutes ago

Did this page help you?