Note: The State Tax API utilizes JSON Patch formatting. Please ensure the use of "application/json-patch+json" in the "Content-Type" header.

Standard Fields:

The State Tax API constructs State Taxes using a standard set of fields. These fields are broken up in 2 categories: Required, Defaulted.

Required Fields:

The following fields are required for each State Tax, and must be in the ADD operation to successfully add a State Tax to a Worker:

• countrySubdivisionCode
• regulationType (this will always be INCOME_TAX)
• isResidentState
• stateAllocationPercent
• correlationID

Defaulted Fields:

The following fields are not required for each State Tax, but will be defaulted to certain values if not otherwise specified differently during the ADD operation:

• filingStatusType
• taxStatusType
• Deductions 
• Extra Withholding Fields

Deductions:

Deductions for each state will be automatically generated during the ADD operation and defaulted to 0. These deductions CANNOT be modified during the ADD operation, and can only be REPLACED after the State Tax has been ADDed.

Extra Withholding Fields:

Similar to the Federal Tax API, additionalAmount, flatDollarOverride, additionalPercent, overridePercent are subject to certain valid field combinations. These are explained in the endpoint documentation for each State Tax endpoint. 

State Specific Fields:

Some states do not follow the field standards as set above. Below is a list of each state and how it differs from the set field standards.

Arizona:

Defaulted Fields:

• filingStatusType - this field is not used
• withholdingPercent - this is an added field that is specific to Arizona

Arkansas:

Defaulted Fields:

• filingStatusType - this field is not used

Connecticut:

Defaulted Fields:

• reductionalAmount - this field is an added Defaulted Field that is specific to Connecticut

Illinois:

Defaulted Fields:

• filingStatusType - this field is not used

Indiana:

Defaulted Fields:

• filingStatusType - this field is not used

Kentucky:

Defaulted Fields:

• filingStatusType - this field is not used

Maryland:

Required Fields:

• countyName - this field is an added Required Field that is specific to Maryland when isResidentState is TRUE

Michigan:

Defaulted Fields:

• filingStatusType - this field is not used

Ohio:

Defaulted Fields:

• filingStatusType - this field is not used

Pennsylvania:

Defaulted Fields:

• filingStatusType - this field is not used

Utah:

Defaulted Fields:

• filingStatusType - this field is not required, but must be ADDed in order to change its value if needed

Note: You may not see filingStatusType in the response body for Utah's State Tax. This means that the field is defaulting to the Federal Tax filingStatusType

Virginia:

Defaulted Fields:

• filingStatusType - this field is not used

Exempt from State Income Tax:

This section focuses on the EXEMPT taxStatusType, which sets the Taxibility field in FLEX to "Employee is not taxable...", and must be done by contacting PAYCHEX support to set up, or now by using the API to set the worker to not be taxable. This is not to be confused with the EXEMPT_FROM_WITHOLDING taxStatusType, which is the taxStatusType you can select in FLEX by choosing the "No" option for the Taxes Withheld field. If a worker is taxable, you should use the EXEMPT_FROM_WITHOLDING taxStatusType. If they are completely not taxable, then you should use the EXEMPT taxStatusType.

Allowable Fields:

The following fields are the only fields allowed when setting taxStatusType to EXEMPT:

• Required Fields
• taxStatusType
• countyName (Maryland only)
• withholdingPercent (Arizona only)
• exemptionReasonDescription

Disallowed Fields:

All other fields not described above are not allowed in any request operation where taxStatusType is EXEMPT. Doing so will throw an error.

States without Income Tax:

Some states do not collect income tax. These states are still able to be added to a Worker to properly allocate state income tax allocation percentages. States that do not collect an income tax should be ADDed using only the standard Required Fields. REPLACE operations remain valid for any allowed field. 

Error Codes:

Below are the error codes that can be returned by the State Tax API. When applicable, the errors will identify which part of the call failed via correlationId, the field name that failed, and that fields value, and any other value information regarding minimums and/or maximums, expected values, value type, etc..

Error Code

Description of Error

TAX100

A required field was not provided in the request

TAX101

A numerical field in the request did not fall in the expected min/max value range

TAX102

A value was specified however it is not valid (example, the value is not one of an expected enumeration)

TAX107

A specified identifier was invalid (workerTaxId, etc.)

TAX108

One of the following fields must be specified but were not

TAX109

A textual field exceeded the maximum length

TAX111

The worker does not have a resident state

TAX112

The worker has more than one resident state

TAX114

The state allocation percentage does not sum to 100

TAX116

Extra withholding choices were specified in an invalid configuration

TAX117

The worker tax has an end date that is not on or before the end date of the client tax

TAX122

The state tax being added to the worker already exists

TAX131

Combined worker and client tax amounts cannot be more than system level totals

TAX135

For a full time worker that is taxable on a tax configured for "not paid by Employer portion", 
the employee percent can't be more than the employee system percent

TAX147

The worker has unprocessed checks that prevent changes to the taxes 

TAX154

The state tax being added is for an unsupported US Territory on a PEO client

TAX163

The request specified fields that are not allowed/supported

TAX167

The state tax being added has no client tax setup

TAX176

Duplicate correlationId in request

TAX177

Duplicate state tax in request

TAX178

The specified worker is of a type that is unsupported

TAX500

Internal server error

TAX989

Internal server error