Company Tax Setup

Every company has a set of federal, state, and state unemployment (SUTA) tax parameters that must be filled in before payroll can run correctly for it — things like the company's FEIN, state tax account numbers, and SUTA rates. Use these two endpoints to read that tax setup and to fill in or change individual parameters.

This section covers company-level tax setup only. Employee-level tax parameters (for example, an employee's state withholding elections) are documented separately.

Get Company Tax Setup

GET https://api.worklio.com/wep/companies/{CLIENT_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.

Returns the company's full tax setup: federal, then one entry per state, then one entry per state for SUTA (State Unemployment Tax Act) registration. Which states appear depends on where the company is based and where its employees work — a company only sees entries for states it actually has a presence in.

Reading the response

Top-level fields:

Field	Type	Description
`effectiveFrom`	string (ISO date)	The effective date of this tax setup.
`isComplete`	boolean	`true` only when `federal`, every entry in `state`, and every entry in `suta` are all complete.
`federal`	object	Federal tax setup. See "Group fields" below.
`state`	array of objects	State income tax and related state payroll tax setup (for example, NY's SDI). One entry per state. See "Group fields" below.
`suta`	array of objects	SUTA (state unemployment) registration and rate setup. One entry per state, separate from `state`. See "Group fields" below.

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

Field	Type	Description
`name`	string	Human-readable name of this tax group, e.g. `"State Tax Setup - NY"`.
`state`	string	Two-letter state code. Present on `state` and `suta` entries only, not on `federal`.
`ein`	string	The group's FEIN or state tax account number. Empty string if not yet set. This mirrors the value of the group's account-number parameter (below) — to change it, update that parameter, not this field.
`isComplete`	boolean	`true` when every required parameter (`isOptional: false`) in this group has a non-empty `value`.
`parameters`	array of objects	The individual tax parameters for this group. See "Parameter fields" below.

Parameter fields (on each entry in parameters):

Field	Type	Description
`taxId`	string	Opaque identifier for this specific parameter. Pass it back in the update call (below) to set this parameter's value. Specific to this company — don't reuse it for another company.
`parameterType`	integer	Controls how `value` should be interpreted. See "Parameter type values" below.
`name`	string	Internal field name, e.g. `AccountNumber`, `_SUTA_RATE`.
`caption`	string	Human-readable label, e.g. `"Tax Account Number"`.
`hint`	string	Help text for the parameter. Empty string if there isn't any.
`value`	string	The parameter's current value. Empty string if not yet set.
`defaultValue`	string	Default value for the parameter, if any.
`isOptional`	boolean	Whether this parameter is required for the group's `isComplete` to be `true`.
`options`	array of objects	Present 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`.
`regEx`	string	Present only on parameters with format validation (e.g. currency, percentage). The pattern `value` must match.
`warning`	string	Present alongside `regEx`. Message describing the expected format, for display if validation fails.
`compatibleStates`	array of strings	Present on some parameters. States this parameter is relevant to.
`isEditableOnlyByAdmin`	boolean	Present on some parameters.
`isVisibleOnlyByAdmin`	boolean	Present on some parameters.

Parameter type values:

Value	Meaning
1	Boolean (true/false). Sometimes paired with `options` giving explicit labels for the two values instead of a plain checkbox.
3	Currency amount. Has a `regEx` restricting it to a dollar amount with up to 2 decimal places.
4	Percentage. Has a `regEx` restricting it to a numeric percentage.
5	Select — choose one value from `options`.
6	Free text.

Example request

require("dotenv").config();

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

async function getCompanyTaxSetup() {
  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);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

getCompanyTaxSetup();

curl -s -X GET "https://api.worklio.com/wep/companies/$CLIENT_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 .

import os
import json

import requests
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.environ.get("API_KEY")
CLIENT_ID = os.environ.get("CLIENT_ID")
URL = f"https://api.worklio.com/wep/companies/{CLIENT_ID}/taxsetup"


def get_company_tax_setup():
    response = requests.get(
        URL,
        headers={
            "accept": "application/json",
            "api-version": "2.0",
            "authorization": f"Bearer {TOKEN}",
            "content-type": "application/json",
            "x-api-version": "2.0",
        },
    )

    print(response.status_code)

    raw = response.text
    print(json.dumps(json.loads(raw), indent=2))

    return response


if __name__ == "__main__":
    get_company_tax_setup()

Example response

A company's tax setup can run to hundreds of parameters once it's registered in several states.

{
  "effectiveFrom": "2026-01-01",
  "isComplete": false,
  "federal": {
    "name": "Federal Tax Setup",
    "ein": "123456789",
    "isComplete": true,
    "parameters": [
      {
        "taxId": "Hn90y4jz7G0znZu8nIRRq5R3V9m6Me4fTBv9GY4uBpY2rK48D__NJeNFwerk@",
        "parameterType": 6,
        "name": "FEIN",
        "caption": "FEIN",
        "hint": "",
        "value": "123456789",
        "defaultValue": "",
        "isOptional": false
      }
    ]
  },
  "state": [
    {
      "name": "State Tax Setup - IL",
      "state": "IL",
      "ein": "",
      "isComplete": false,
      "parameters": [
        {
          "taxId": "JfO9n0ldy6le2BnRFX6kn0e52i3OUzhXpRX6XgKWMtzaQAf_zSGPWeWmiMM1D1A@@",
          "parameterType": 6,
          "name": "AccountNumber",
          "caption": "Tax Account Number",
          "hint": "",
          "value": "",
          "defaultValue": "",
          "isOptional": false
        },
        {
          "taxId": "AVxescmJpxcvAHKtqzlBy4lyyITVATu0T3fhvkG-I0hzgWX6WnaOWqiuPA_bgWw@@",
          "parameterType": 1,
          "name": "_IS_EXEMPT_ER",
          "caption": "Exempt From SUTA",
          "hint": "",
          "value": "false",
          "defaultValue": "",
          "isOptional": false
        }
      ]
    },
    {
      "name": "State Tax Setup - NY",
      "state": "NY",
      "ein": "",
      "isComplete": false,
      "parameters": [
        {
          "taxId": "WuwPB_TmpZoHRI7tbbsa5pI6yLI4C_udeZtB4db8t2U3Q72aaxlH6_oEy0o8d6g@@",
          "parameterType": 6,
          "name": "AccountNumber",
          "caption": "Tax Account Number",
          "hint": "",
          "value": "",
          "defaultValue": "",
          "isOptional": false
        },
        {
          "taxId": "VDfgOwaZLmGWP6kT_Si6zgKeJrS-LAuvjUXjQZXS_LdlOzO1mmd1P_P6BMtuVHA@@",
          "parameterType": 1,
          "name": "_IS_EXEMPT_ER",
          "caption": "Exempt From SUTA",
          "hint": "",
          "value": "false",
          "defaultValue": "",
          "isOptional": false
        },
        {
          "taxId": "VDfgOwaZLmGWM6UT_Si6zgKeJrS-LAuvjUXjQZXS_LdlJy-1mmd1P_P6BMtuVHA@@",
          "parameterType": 5,
          "name": "SDIHandling",
          "caption": "SDI Handling",
          "hint": "SDI Handling defines whether SDI is handled by the state or a private company",
          "value": "0",
          "defaultValue": "",
          "isOptional": false,
          "options": [
            {
              "caption": "None",
              "description": "",
              "value": "0"
            },
            {
              "caption": "Private Policy, Billed Monthly",
              "description": "",
              "value": "11"
            },
            {
              "caption": "Private Policy, Billed Each Pay Period",
              "description": "",
              "value": "12"
            },
            {
              "caption": "Private Policy, Collect EE Portion Only",
              "description": "",
              "value": "202"
            }
          ]
        },
        {
          "taxId": "JfO9n0ldy6lS9DnRFX6kn0e52i3aRzhXuQn6XgKWMtzaUBf_zSmDXeWmiMM1D3Q@@",
          "parameterType": 3,
          "name": "SDI_PREMIUM",
          "caption": "Monthly SDI Premium per EE",
          "hint": "SDI Cost amount should be the full premium, including EE share if cost sharing is enabled.",
          "value": "",
          "defaultValue": "",
          "isOptional": false,
          "regEx": "^([0-9]+([.][0-9]{0,2})?)$",
          "warning": "Please enter valid ($) amount with up to 2 decimal places."
        },
        {
          "taxId": "tVv3vCoaVQgIAiTs0XIH4wCH2bNoEVupTsiYwWFLkH9DraYxyltcH_lp-lpWrgw@@",
          "parameterType": 1,
          "name": "SDI_SHARE_WITH_EE",
          "caption": "Share SDI Cost with EE",
          "hint": "",
          "value": "false",
          "defaultValue": "",
          "isOptional": false
        },
        {
          "taxId": "KrGrSDADbV7w4EQFO6VLo7XGUdZHLAOpKZpadpIy3NpIW9_NJe8l_aaIwxFnc_w@@",
          "parameterType": 1,
          "name": "SDI_RETURN_TO_CLIENT",
          "caption": "Credit Back SDI To Client",
          "hint": "",
          "value": "false",
          "defaultValue": "",
          "isOptional": false
        },
        {
          "taxId": "gsW2vZtLqcje_YWbv8kTZ_xnJt1IRF7RuLUzYzNk99nLDAlTmRaomMURG6hA@",
          "compatibleStates": ["MO", "NV", "NY"],
          "parameterType": 4,
          "name": "_ER_POP_RATE",
          "caption": "ER POP Rate (%) - New York MCTMT Employer Payroll Tax - Zone 1",
          "hint": "<b>Zone 1</b> includes the counties of New York (Manhattan), Bronx, Kings (Brooklyn), Queens and Richmond (Staten Island).",
          "isOptional": true,
          "regEx": "^([0-9]{1,2}([.][0-9]{0,4})?)$",
          "warning": "Please enter ER POP rate as a percentage value with up to 4 decimal places",
          "isEditableOnlyByAdmin": true
        },
        {
          "taxId": "OFf9PpnEUX1DiIYjwftxXidAZ-V56l4ioiaoingb861Bk0npxpDDEUM_kdYg@",
          "compatibleStates": ["MO", "NV", "NY"],
          "parameterType": 4,
          "name": "_ER_POP_RATE",
          "caption": "ER POP Rate (%) - New York MCTMT Employer Payroll Tax - Zone 2",
          "hint": "<b>Zone 2</b> includes the counties of Rockland, Nassau, Suffolk, Orange, Putnam, Dutchess and Westchester.",
          "isOptional": true,
          "regEx": "^([0-9]{1,2}([.][0-9]{0,4})?)$",
          "warning": "Please enter ER POP rate as a percentage value with up to 4 decimal places",
          "isEditableOnlyByAdmin": true
        },
        {
          "taxId": "Yj_BigCWw1B7hfTuXjOi0tjSXBPv3SGzBYWmlI81T1_Z8ncZR-v6BMtKPHeM@",
          "compatibleStates": ["ALL"],
          "parameterType": 1,
          "name": "_IS_SUBJECTTO_ER",
          "caption": "Subject to tax - New York Employer Compensation Expense Tax",
          "hint": "Please specify whether employer is subject to this tax",
          "isOptional": false,
          "isEditableOnlyByAdmin": true,
          "options": [
            { "caption": "0", "description": "", "value": "false" },
            { "caption": "1", "description": "", "value": "true" }
          ]
        },
        {
          "taxId": "uvuIK3edzDwSwWnBNwY35IvFz2QRT_1e6PjFFTvoa1utpj2qTzwH-WneFjg@@",
          "compatibleStates": ["ALL"],
          "parameterType": 1,
          "name": "_IS_EXEMPT_ER",
          "caption": "Exempt From New York Employer Compensation Expense Tax",
          "hint": "Check the box to indicate exemption from this tax.",
          "isOptional": false,
          "isEditableOnlyByAdmin": true,
          "isVisibleOnlyByAdmin": true,
          "options": [
            { "caption": "0", "description": "", "value": "false" },
            { "caption": "1", "description": "", "value": "true" }
          ]
        },
        {
          "taxId": "OFf9PpnEUXl3sI4jwftxXidAZ-V56l4ioiaoqjgDn6lR60mFvojDEUMb-dA@@",
          "compatibleStates": ["ALL"],
          "parameterType": 1,
          "name": "_IS_EXEMPT_ER",
          "caption": "Exempt From New York MCTMT Employer Payroll Tax - Zone 1",
          "hint": "If you mark exempt, the employer is exempt from the whole tax. For the MCTMT tax, the field name contains the phrase Zone 1 but exempt applies to the entire tax as such, not to individual zones. (the name is generated automatically from a variable referring to the database tag and thus it is misleading)",
          "isOptional": false,
          "isEditableOnlyByAdmin": true,
          "isVisibleOnlyByAdmin": true,
          "options": [
            { "caption": "0", "description": "", "value": "false" },
            { "caption": "1", "description": "", "value": "true" }
          ]
        }
      ]
    }
  ],
  "suta": [
    {
      "name": "SUTA Tax Setup - IL",
      "state": "IL",
      "ein": "",
      "isComplete": false,
      "parameters": [
        {
          "taxId": "dlDj6_zuGfpHRS22kU3PL_gvk5ATTsUICCKF_KVHMwMEh7GveAUz5Q6omMU1c4g@@",
          "parameterType": 6,
          "name": "AccountNumber",
          "caption": "Tax Account Number",
          "hint": "",
          "value": "",
          "defaultValue": "",
          "isOptional": false
        },
        {
          "taxId": "LKd8MW6lmsT4qYAr4Ep3UcpNqks0D_05piJ25jKsqlBnj8khj1nlpojDNQ9Q@",
          "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", "WA"],
          "parameterType": 4,
          "name": "_SUTA_RATE",
          "caption": "SUTA Rate - Illinois State Unemployment Tax",
          "hint": "Enter SUTA rate applicable to this TRID.",
          "value": "",
          "defaultValue": "",
          "isOptional": false,
          "regEx": "^([0-9]{1,2}([.][0-9]{0,4})?)$",
          "warning": "Please enter SUTA rate as a percentage value with up to 4 decimal places",
          "isEditableOnlyByAdmin": true
        }
      ]
    },
    {
      "name": "SUTA Tax Setup - NY",
      "state": "NY",
      "ein": "",
      "isComplete": false,
      "parameters": [
        {
          "taxId": "0LI1-mZgk6k5mstm5gfoOkxzn9Et60G1-vzLFTNLwe4faS_z-girUhg7x1nnmkQ@@",
          "parameterType": 6,
          "name": "AccountNumber",
          "caption": "Tax Account Number",
          "hint": "",
          "value": "",
          "defaultValue": "",
          "isOptional": false
        },
        {
          "taxId": "naqRPL7nHD-T7IZSxRkUzvGEtS9Pf3Sr5dtwBSv9Asj0tRUzhBM3xbox7htQ@",
          "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", "WA"],
          "parameterType": 4,
          "name": "_SUTA_RATE",
          "caption": "SUTA Rate - New York State Unemployment Tax",
          "hint": "Enter SUTA rate applicable to this TRID.",
          "value": "",
          "defaultValue": "",
          "isOptional": false,
          "regEx": "^([0-9]{1,2}([.][0-9]{0,4})?)$",
          "warning": "Please enter SUTA rate as a percentage value with up to 4 decimal places",
          "isEditableOnlyByAdmin": true
        }
      ]
    }
  ]
}

🚧
state and suta are separate arrays for the same state. State income tax withholding and related state payroll taxes (like NY's SDI and MCTMT) live under state; state unemployment insurance registration and rate live under suta. Update the one that matches the tax you're setting.

Update Company Tax Setup

POST https://api.worklio.com/wep/companies/{CLIENT_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.

Sets the value of one or more tax parameters. This is a targeted update, not a full replacement of the company'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:

Field	Type	Required	Description
`taxId`	string	Yes	The parameter's `taxId`, from a Get Company Tax Setup response.
`value`	string	Yes	The 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 `value`s.

Example request

This example sets Guide Company's New York SUTA tax account number and SUTA rate — the AccountNumber and _SUTA_RATE parameters from the suta NY entry above.

require("dotenv").config();

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

const payload = [
  {
    taxId: "0LI1-mZgk6k5mstm5gfoOkxzn9Et60G1-vzLFTNLwe4faS_z-girUhg7x1nnmkQ@@", // NY SUTA - Tax Account Number
    value: "123456789"
  },
  {
    taxId: "naqRPL7nHD-T7IZSxRkUzvGEtS9Pf3Sr5dtwBSv9Asj0tRUzhBM3xbox7htQ@", // NY SUTA - SUTA Rate
    value: "2.2"
  }
];

async function updateCompanyTaxSetup() {
  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
}

updateCompanyTaxSetup();

curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_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": "0LI1-mZgk6k5mstm5gfoOkxzn9Et60G1-vzLFTNLwe4faS_z-girUhg7x1nnmkQ@@",
      "value": "123456789"
    },
    {
      "taxId": "naqRPL7nHD-T7IZSxRkUzvGEtS9Pf3Sr5dtwBSv9Asj0tRUzhBM3xbox7htQ@",
      "value": "2.2"
    }
  ]'

import os
import json

import requests
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.environ.get("API_KEY")
CLIENT_ID = os.environ.get("CLIENT_ID")
URL = f"https://api.worklio.com/wep/companies/{CLIENT_ID}/taxsetup"

payload = [
    {
        "taxId": "0LI1-mZgk6k5mstm5gfoOkxzn9Et60G1-vzLFTNLwe4faS_z-girUhg7x1nnmkQ@@",
        "value": "123456789"
    },
    {
        "taxId": "naqRPL7nHD-T7IZSxRkUzvGEtS9Pf3Sr5dtwBSv9Asj0tRUzhBM3xbox7htQ@",
        "value": "2.2"
    }
]
def get_company_tax_setup():
    response = requests.post(
        URL,
        headers={
            "accept": "application/json",
            "api-version": "2.0",
            "authorization": f"Bearer {TOKEN}",
            "content-type": "application/json",
            "x-api-version": "2.0",
        },
        json=payload
    )

    print(response.status_code)

    raw = response.text
    print(json.dumps(json.loads(raw), indent=2))

    return response


if __name__ == "__main__":
    get_company_tax_setup()

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 Company Tax Setup again.

🚧
Read taxId values fresh from a GET response before sending an update. They're specific to each Get Company Tax Setup call — don't cache or hardcode them, and don't reuse a taxId from one company for another.

Get Company Tax Setup

Reading the response

Example request

Example response

state and suta are separate arrays for the same state. State income tax withholding and related state payroll taxes (like NY's SDI and MCTMT) live under state; state unemployment insurance registration and rate live under suta. Update the one that matches the tax you're setting.

Update Company Tax Setup

Example request

Example response

Read taxId values fresh from a GET response before sending an update. They're specific to each Get Company Tax Setup call — don't cache or hardcode them, and don't reuse a taxId from one company for another.

`state` and `suta` are separate arrays for the same state. State income tax withholding and related state payroll taxes (like NY's SDI and MCTMT) live under `state`; state unemployment insurance registration and rate live under `suta`. Update the one that matches the tax you're setting.