Sign in for full access

Finding Applicable Taxes

Part 2 of 3

Suggest Edits

Now that we have location codes corresponding to Olivia's home and work addresses, we can find the taxes that will potentially apply for this payroll.

We're going to be making a single request ("SetTaxListRequest") to the setTaxList endpoint:

https://ste-staging.symmetry.com/ste-hosted/v2/setTaxList

This request will use the following three location codes that we determined in the previous step:

00-000-0000: The location code used for all federal taxes
04-000-0001: The location code for Olivia's work address in Arizona
04-000-0002: The location code for Olivia's home address in Arizona

📘

Don't forget that we use 00-000-0000 as the location code for all federal taxes!

While you could make a separate request for each location code, you would then have to account for any repeated taxes in your own system. For example, both the home and work location codes will return the Arizona State Tax, but you wouldn't actually want to set it up twice!

So instead, we'll be sending all three location codes as separate objects within a single request. That way the engine will consolidate duplicate taxes where possible.

Sample SetTaxListRequest

The following request will return all potentially applicable taxes based on the three location codes listed above:

{
  "SetTaxListRequest": {
    "taxReference": [
      {
        "locationCode": "00-000-0000",
        "payDate": "2023-01-13",
        "isResident": true,
        "municipalityCode": null,
        "schoolCode": null
      },
      {
        "locationCode": "04-000-0001",
        "payDate": "2023-01-13",
        "isResident": false,
        "municipalityCode": null,
        "schoolCode": null
      },
      {
        "locationCode": "04-000-0002",
        "payDate": "2023-01-13",
        "isResident": true,
        "municipalityCode": null,
        "schoolCode": null
      }
    ]
  }
}

SetTaxListRequest breakdown

Each object within the "taxReference" array has the following properties:

"locationCode"

One of the location codes that we generated in the previous section of this guide (or "00-000-0000" for federal).

"payDate"

The actual date of the payroll in YYYY-MM-DD format. In the example above, we're assuming that Olivia's employer runs payroll on January 13, 2023 ("2023-01-13"). Since we're setting up multiple location codes here, we've also made sure that the date is the same for all three entries.

Note that because this is a string, it must be surrounded by quotation marks. You can't just enter 2023-01-13!

"isResident"

We've entered true for the home location code and false for the work location code. We've also entered true for the federal location code, since that location code represents taxes on a nationwide level and Olivia lives in the U.S.!

"municipalityCode", "schoolCode"

Some states, such as Ohio and Pennsylvania, may require additional codes in order to properly pinpoint the applicable taxes. If these were applicable, these fields would have been returned as part of the LocationCodeResponse earlier. Since neither of those fields were returned for our Arizona addresses, we've set both of these to null instead.

Sample SetTaxListResponse

After we send that request, we'll get the following lengthy response back from the STE:

{
  "SetTaxListResponse": {
    "taxItem": [
      {
        "creditLimit": 0,
        "stateName": "Federal Tax",
        "taxEffectiveDate": "2023-01-01",
        "rate": 0.062,
        "wageBase": 160200,
        "stateCode": "00",
        "isEmployerTax": true,
        "taxLimitPeriod": "Annually",
        "taxLimit": 9932.4,
        "uniqueTaxID": "00-000-0000-ER_FICA-000",
        "stateAbbreviation": "FED",
        "taxInstallationDate": "2022-10-19",
        "description": "Employer FICA Tax",
        "isResident": true,
        "credit": 0
      },
      {
        "creditLimit": 0,
        "stateName": "Federal Tax",
        "taxEffectiveDate": "2011-07-01",
        "rate": 0.06,
        "wageBase": 7000,
        "stateCode": "00",
        "isEmployerTax": true,
        "taxLimitPeriod": "None",
        "taxLimit": 0,
        "uniqueTaxID": "00-000-0000-ER_FUTA-000",
        "stateAbbreviation": "FED",
        "taxInstallationDate": "2011-07-01",
        "description": "Federal Unemployment Tax",
        "isResident": true,
        "credit": 0
      },
      {
        "creditLimit": 0,
        "stateName": "Federal Tax",
        "taxEffectiveDate": "1900-01-01",
        "rate": 0.0145,
        "wageBase": 0,
        "stateCode": "00",
        "isEmployerTax": true,
        "taxLimitPeriod": "None",
        "taxLimit": 0,
        "uniqueTaxID": "00-000-0000-ER_MEDI-000",
        "stateAbbreviation": "FED",
        "taxInstallationDate": "1900-01-01",
        "description": "Employer Medicare Tax",
        "isResident": true,
        "credit": 0
      },
      {
        "creditLimit": 0,
        "stateName": "Federal Tax",
        "taxEffectiveDate": "2023-01-01",
        "rate": 0.062,
        "wageBase": 160200,
        "stateCode": "00",
        "isEmployerTax": false,
        "taxLimitPeriod": "Annually",
        "taxLimit": 9932.4,
        "uniqueTaxID": "00-000-0000-FICA-000",
        "stateAbbreviation": "FED",
        "taxInstallationDate": "2021-10-19",
        "description": "FICA",
        "isResident": true,
        "credit": 0
      },
      {
        "credit": 0,
        "stateName": "Federal Tax",
        "stateCode": "00",
        "taxEffectiveDate": "1900-01-01",
        "rate": 0,
        "wageBase": 0,
        "creditLimit": 0,
        "isEmployerTax": false,
        "taxLimitPeriod": "None",
        "taxLimit": 0,
        "uniqueTaxID": "00-000-0000-FIT-000",
        "stateAbbreviation": "FED",
        "taxInstallationDate": "1900-01-01",
        "description": "Federal Income Tax",
        "isResident": true,
        "jurisdictionData": [
          {
            "certificateLineNo": "",
            "taxEffectiveDate": "2020-01-01",
            "regexType": "PickList",
            "helpText": "'TRUE' if employee wants to fill 2020_w4 and 'FALSE' if employee wants to fill 2019 form",
            "dataType": "Boolean",
            "isOptional": true,
            "defaultValue": "FALSE",
            "regex": "^(TRUE|FALSE)$",
            "uniqueTaxID": "00-000-0000-FIT-000",
            "stateAbbreviation": "FED",
            "regexDescription": "'TRUE'-using 2020 W4 or 'FALSE'",
            "description": "2020 W4",
            "stateCode": "00",
            "parameterName": "2020_W4"
          },
          {
            "certificateLineNo": "Form W-4, Step 1 Box (c)",
            "defaultValue": "S",
            "taxEffectiveDate": "2023-01-01",
            "regexType": "PickList",
            "dataType": "String",
            "helpText": "'S'-single or married filing separately, 'M'-married filing jointly or qualifying surviving spouse, 'H'-head of household, or 'NRA'-nonresident alien.",
            "isOptional": false,
            "listValues": "S=Single or Married filing separately, M=Married filing jointly or Qualifying surviving spouse, H=Head of household, NRA=Nonresident Alien",
            "regex": "^(S|M|H|NRA)$",
            "uniqueTaxID": "00-000-0000-FIT-000",
            "stateAbbreviation": "FED",
            "regexDescription": "'S'-single or married filing separately, 'M'-married filing jointly or qualifying surviving spouse, 'H'-head of household, or 'NRA'-nonresident alien.",
            "description": "Filing Status",
            "stateCode": "00",
            "parameterName": "FILINGSTATUS"
          },
          {
            "certificateLineNo": "",
            "taxEffectiveDate": "1900-01-01",
            "regexType": "SingleValue",
            "helpText": "The total number of allowances for STATE tax.",
            "dataType": "Integer",
            "isOptional": true,
            "defaultValue": "0",
            "regex": "^([0-9]+)$",
            "uniqueTaxID": "00-000-0000-FIT-000",
            "stateAbbreviation": "FED",
            "regexDescription": "The total number of allowances.",
            "description": "Total Allowances",
            "stateCode": "00",
            "parameterName": "TOTALALLOWANCES"
          },
          {
            "certificateLineNo": "Form W-4, Step 2 Box (c)",
            "taxEffectiveDate": "2020-01-01",
            "regexType": "PickList",
            "helpText": "Set to 'TRUE' if W4 Box 2 (c) is checked.",
            "dataType": "Boolean",
            "isOptional": false,
            "defaultValue": "FALSE",
            "regex": "^(TRUE|FALSE)$",
            "uniqueTaxID": "00-000-0000-FIT-000",
            "stateAbbreviation": "FED",
            "regexDescription": "'TRUE'-has two jobs or 'FALSE'",
            "description": "Two Jobs",
            "stateCode": "00",
            "parameterName": "TWO_JOBS"
          },
          {
            "certificateLineNo": "Form W-4, Step 3",
            "taxEffectiveDate": "2020-01-01",
            "regexType": "SingleValue",
            "helpText": "Dependent amount from W4 Step 3",
            "dataType": "Dollar",
            "isOptional": false,
            "defaultValue": "0.0",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "uniqueTaxID": "00-000-0000-FIT-000",
            "stateAbbreviation": "FED",
            "regexDescription": "Dependent amount from W4 Step 3",
            "description": "Dependent Amount",
            "stateCode": "00",
            "parameterName": "DEPENDENTS_AMT"
          },
          {
            "certificateLineNo": "",
            "taxEffectiveDate": "1900-01-01",
            "regexType": "SingleValue",
            "helpText": "The most recent amount withheld.",
            "dataType": "Dollar",
            "isOptional": true,
            "defaultValue": "0.0",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "uniqueTaxID": "00-000-0000-FIT-000",
            "stateAbbreviation": "FED",
            "regexDescription": "The most recent amount withheld.",
            "description": "Most Recent Withholding Amount",
            "stateCode": "00",
            "parameterName": "MOST_RECENT_WH"
          },
          {
            "certificateLineNo": "Form W-4P, Step 2 (b) (iii)",
            "taxEffectiveDate": "2022-01-01",
            "regexType": "SingleValue",
            "helpText": "Total income from a job or multiple pensions/annuities from W4P Step 2 (b) (iii)",
            "dataType": "Dollar",
            "isOptional": true,
            "defaultValue": "0.0",
            "regex": "^(-?[0-9]+([.][0-9]{0,2})?)$",
            "uniqueTaxID": "00-000-0000-FIT-000",
            "stateAbbreviation": "FED",
            "regexDescription": "Total income from a job or multiple pensions/annuities from W4P Step 2 (b) (iii)",
            "description": "Job Pension Total",
            "stateCode": "00",
            "parameterName": "JOB_PENSION_TOTAL"
          },
          {
            "certificateLineNo": "Form W-4, Step 4 Box (a)",
            "taxEffectiveDate": "2020-01-01",
            "regexType": "SingleValue",
            "helpText": "Other income from W4 Step 4 (a)",
            "dataType": "Dollar",
            "isOptional": false,
            "defaultValue": "0.0",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "uniqueTaxID": "00-000-0000-FIT-000",
            "stateAbbreviation": "FED",
            "regexDescription": "Other income from W4 Step 4 (a)",
            "description": "Other Income",
            "stateCode": "00",
            "parameterName": "OTHER_INCOME"
          },
          {
            "certificateLineNo": "Form W-4, Step 4 Box (b)",
            "taxEffectiveDate": "2020-01-01",
            "regexType": "SingleValue",
            "helpText": "Deductions from W4 Step 4 (b)",
            "dataType": "Dollar",
            "isOptional": false,
            "defaultValue": "0.0",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "uniqueTaxID": "00-000-0000-FIT-000",
            "stateAbbreviation": "FED",
            "regexDescription": "Deductions from W4 Step 4 (b)",
            "description": "Deductions",
            "stateCode": "00",
            "parameterName": "DEDUCTIONS"
          },
          {
            "certificateLineNo": "Exemption amount from Form 8233",
            "taxEffectiveDate": "2020-01-01",
            "regexType": "SingleValue",
            "helpText": "Exemption amount from Form 8233",
            "dataType": "Dollar",
            "isOptional": true,
            "defaultValue": "0.0",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "uniqueTaxID": "00-000-0000-FIT-000",
            "stateAbbreviation": "FED",
            "regexDescription": "Exemption amount from Form 8233",
            "description": "NRA Exemption Amount",
            "stateCode": "00",
            "parameterName": "NRA_EXEMPTION_AMT"
          }
        ]
      },
      {
        "creditLimit": 0,
        "stateName": "Federal Tax",
        "taxEffectiveDate": "1900-01-01",
        "rate": 0.0145,
        "wageBase": 0,
        "stateCode": "00",
        "isEmployerTax": false,
        "taxLimitPeriod": "None",
        "taxLimit": 0,
        "uniqueTaxID": "00-000-0000-MEDI-000",
        "stateAbbreviation": "FED",
        "taxInstallationDate": "1900-01-01",
        "description": "Medicare",
        "isResident": true,
        "credit": 0
      },
      {
        "creditLimit": 0,
        "stateName": "Federal Tax",
        "taxEffectiveDate": "2013-01-01",
        "rate": 0.009,
        "wageBase": 0,
        "stateCode": "00",
        "isEmployerTax": false,
        "taxLimitPeriod": "None",
        "taxLimit": 0,
        "uniqueTaxID": "00-000-0000-MEDI2-000",
        "stateAbbreviation": "FED",
        "taxInstallationDate": "2013-01-01",
        "description": "Additional Medicare",
        "isResident": true,
        "credit": 0
      },
      {
        "creditLimit": 0,
        "stateName": "Arizona",
        "taxEffectiveDate": "2023-01-01",
        "rate": 0,
        "wageBase": 8000,
        "stateCode": "04",
        "isEmployerTax": true,
        "taxLimitPeriod": "None",
        "taxLimit": 0,
        "uniqueTaxID": "04-000-0000-ER_SUTA-000",
        "stateAbbreviation": "AZ",
        "taxInstallationDate": "2022-10-10",
        "description": "Arizona State Unemployment Tax",
        "isResident": true,
        "credit": 0
      },
      {
        "credit": 0,
        "stateName": "Arizona",
        "stateCode": "04",
        "taxEffectiveDate": "1900-01-01",
        "rate": 0,
        "wageBase": 0,
        "creditLimit": 0,
        "isEmployerTax": false,
        "taxLimitPeriod": "None",
        "taxLimit": 0,
        "uniqueTaxID": "04-000-0000-SIT-000",
        "stateAbbreviation": "AZ",
        "taxInstallationDate": "1900-01-01",
        "description": "Arizona State Tax",
        "isResident": true,
        "jurisdictionData": [
          {
            "certificateLineNo": "Form A-4, Box 1 or 2",
            "defaultValue": "2.0",
            "taxEffectiveDate": "2023-01-01",
            "regexType": "PickList",
            "dataType": "Percentage",
            "helpText": "The percentage of state tax to withhold.",
            "isOptional": false,
            "listValues": "0=Zero,0.5=0.5,1.0=1.0,1.5=1.5,2.0=2.0,2.5=2.5,3.0=3.0,3.5=3.5",
            "regex": "^(0|0.5|1.0|1.5|2.0|2.5|3.0|3.5)$",
            "uniqueTaxID": "04-000-0000-SIT-000",
            "stateAbbreviation": "AZ",
            "regexDescription": "The percentage of state tax to withhold.",
            "description": "State elected percentage rate",
            "stateCode": "04",
            "parameterName": "PERCENTSTATE"
          },
          {
            "certificateLineNo": "",
            "taxEffectiveDate": "1900-01-01",
            "regexType": "SingleValue",
            "helpText": "The most recent amount withheld.",
            "dataType": "Dollar",
            "isOptional": true,
            "defaultValue": "0.0",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "uniqueTaxID": "04-000-0000-SIT-000",
            "stateAbbreviation": "AZ",
            "regexDescription": "The most recent amount withheld.",
            "description": "Most Recent Withholding Amount",
            "stateCode": "04",
            "parameterName": "MOST_RECENT_WH"
          }
        ]
      }
    ],
    "transactionStamp": {
      "failedTransactions": 0,
      "schemaVersion": "v2",
      "totalTransactions": 1,
      "calcDateTime": "2023-04-02T19:13:58Z",
      "steVersion": "2023-R4",
      "transactionType": "SetTaxList"
    },
    "errorStatus": {
      "errorCode": 0,
      "errorMessage": "No error"
    }
  }
}

SetTaxListResponse breakdown

Each object within the "taxItem" array represents a separate tax. Most of the properties returned with each tax are purely informational, but we'll need to know about the following ones for right now:

"uniqueTaxID"

The single most important field returned here. As mentioned in our introduction to basic concepts in the STE, these tax IDs are how you'll tell the STE which taxes you actually want calculated. Every tax in the Symmetry Tax Engine has a matching unique tax ID.

If you're a currently licensed STE client, please see Symmetry Unique Tax IDs in our Client Support Center for more information on how tax IDs are formatted and what each part of an ID represents.

"description"

The "user friendly" name of the tax.

"taxEffectiveDate"

The effective date of the most recent update to this tax, prior to the pay date that you input in your request. For example, if the engine already had a 2024 rate update for one of these taxes, it would still not return a 2024 effective date because we entered a 2023 pay date!

Like the input pay date, this will be in YYYY-MM-DD format.

"isResident"

If the tax was returned as the result of a home location code entry in the request ("isResident": true), then this will also be true. If it was because of a work location entry ("isResident": false), then this will also be false.

If the tax could have come from either the home and work location code entry (as is the case with the Arizona taxes returned here), then this will be true.

"jurisdictionData"

You'll notice that the federal income tax ("uniqueTaxID": "00-000-0000-FIT-000") and Arizona state tax ("uniqueTaxID": "04-000-0000-SIT-000") were returned with an extra property that the other taxes don't have: "jurisdictionData".

This is returned when the tax will require you to know additional special information about the employee in order to calculate it properly. In the STE, these special elements are commonly referred to as miscellaneous parameters. There are normal parameters that are common to the setup of all taxes in the engine, while these miscellaneous parameters are unique to the specific taxes that they are attached to.

As before, there are several properties returned for each miscellaneous parameter, but we're only going to focus on the ones that we need right now:

  • "parameterName": The engine's "official name" for the miscellaneous parameter — you can think of this like the ID of the parameter. When you go to set up the tax, you will need to enter this parameter name exactly as written!
    • We'll use the federal FILINGSTATUS miscellaneous parameter ("parameterName": "FILINGSTATUS") as an example for the rest of this section.
  • "description": The "plain English" name of the parameter. For FILINGSTATUS, this is fittingly just "Filing Status."
  • "uniqueTaxID": A reference to the specific tax that this miscellaneous parameter belongs to.
    • "uniqueTaxID": "00-000-0000-FIT-000" indicates that FILINGSTATUS belongs to the federal income tax. This may appear obvious since it's included as part of the federal income tax object, but some states also have FILINGSTATUS miscellaneous parameters, and may have a different set of filing statuses than the federal tax. This allows you to easily keep track of which parameter goes with which tax.
  • "isOptional": Whether this miscellaneous parameter is considered optional or not. In most cases, the engine will return a warning if you are missing any required parameters when you go to calculate payroll taxes.
    • FILINGSTATUS is not listed as optional ("isOptional": false). Knowing an employee's filing status is critical to calculating their federal income tax correctly!
  • "certificateLineNo": If this miscellaneous parameter correlates with a specific line on an employee's tax form, it will be listed here. For 2023, an employee's federal filing status comes from "Form W-4, Step 1 Box (c)." You can see the federal Form W-4 here.
  • "regexType": This will either be "PickList" or "SingleValue".
    • "PickList" means there are a finite number of values that the engine will accept for this miscellaneous parameter (for example, federal FILINGSTATUS can only be set to valid federal filing statuses!)
    • "SingleValue" means that there are no limits on the possible input values (as long as the input is the correct data type!)
  • "listValues": If "regexType" is "PickList", then this will be returned with a list of the accepted values.
    • FILINGSTATUS has 4 acceptable values listed ("listValues": "S=Single or Married filing separately, M=Married filing jointly or Qualifying surviving spouse, H=Head of household, NRA=Nonresident Alien"). This means that the acceptable input values for FILINGSTATUS are:
      • "S": The employee selected the federal filing status of _"Single or Married filing separately."
      • "M": The employee selected the federal filing status of "Married filing jointly or Qualifying surviving spouse."
      • "H": The employee selected the federal filing status of "Head of household."
      • "NRA": While Notice 1392states that nonresident aliens should always check the "Single or Married filing separately" filing status, the payroll withholding calculation is handled differently. Therefore, this is listed as a separate filing status option.
  • "defaultValue": If you don't set this miscellaneous parameter (or if you set it to an invalid value), this is the default value that the engine will use instead.
    • For FILINGSTATUS, "defaultValue": "S" means that if you set it correctly, the engine will assume a filing status of "Single or Married filing separately." If the employee had actually selected "Married filing jointly or Qualifying surviving spouse" on their W-4, this would cause a pretty big discrepancy in their payroll withholding!

Determining what information we need

In order to correctly set up those miscellaneous parameter, we'll first need some info from the tax forms that Olivia filled out when she began her employment:

  • When Olivia filled out her federal Form W-4, she selected a filing status of "Single or Married filing separately" in Step 1(c). She did not complete Steps 2 through 4, since they did not apply to her.
  • Since Olivia works in Arizona, she also filled out Arizona Form A-4 and selected a withholding percentage of 2.5%.

Some miscellaneous parameters are only used for special scenarios, so before we continue, let's call out the miscellaneous parameters that we won't need to use for this calculation. 

  • TOTALALLOWANCES is only used when the employee has filled out a pre-2020 Form W-4. Because Olivia started employment in 2023, she filled out a more recent W-4.
  • JOB_PENSION_TOTAL is only needed for pension tax calculations, when the employee has filled out a Form W-4P.
  • NRA_EXEMPTION_AMT is only used in special nonresident alien withholding situations.
  • MOST_RECENT_WH (for both the federal income tax and Arizona state tax) is only used when calculating withholding on bonuses in a certain way. This is just a regular payroll, so we don't need this for now.

We'll want to set all of the other miscellaneous parameters. With the information from Olivia's W-4 and A-4, we know that we need to set the miscellaneous parameters as follows:

  • 2020_W4 will be set to "true" because Olivia did not fill out a pre-2020 federal Form W-4.
  • FILINGSTATUS will be set to "S" because Olivia selected "Single or Married filing separately" in Step 1(c).
  • TWO_JOBS will be set to "false" because since Olivia did not check the box in Step 2(c).
  • DEPENDENTS_AMT, OTHER_INCOME, and DEDUCTIONS will all be set to "0", since Olivia did not complete Step 3 or Step 4.
  • PERCENTSTATE will be set to "2.5" to match Olivia's selection on Arizona Form A-4.

👍

In summary, we now have a list of employee taxes to be calculated:

  • 00-000-0000-FIT-000 (Federal Income Tax)
  • 00-000-0000-FICA-000 (FICA/Social Security)
  • 00-000-0000-MEDI-000 (Medicare)
  • 00-000-0000-MEDI2-000 (Additional Medicare)
  • 04-000-0000-SIT-000 (Arizona State Tax)

We also have a list of miscellaneous parameters that need to be set up in order to get accurate tax withholding amounts.

With all of this info, we can finally move onto calculating the taxes!

Updated 3 months ago

What’s Next

Next we'll calculate payroll taxes and determine Olivia's net pay!

Jump to top