> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rollfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Employee Tax Guide

### Overview

* Employee payroll taxes are applied at three levels: **federal, state, and municipal**.
* This guide explains how to add employee tax information to ensure accurate payroll withholding and reporting.

***

### 🔹 Federal W-4

Use the [addW4Information](https://developer.rollfi.xyz/api-reference/useronboarding/addW4Information) API to capture all federal withholding details required for payroll processing.

***

### 🔹 State W-4

State W-4 imports are more complex because field requirements vary by state. Follow these steps to add an employee’s state tax information:

1. Use the [getStateW4FormFields](https://developer.rollfi.xyz/api-reference/reports/getStateW4FormFeilds) endpoint to retrieve the state-specific form fields required for the employee.
2. Submit the employee’s state tax details using the `addStateW4Information` API. A sample request is shown below:

```json theme={null}
{
  "method": "addStateW4Information",
  "employeeId": "A31A0E84-3643-405A-B0E4-D229D0A194FB",
  "stateW4Information": {
    "Filing Status": "Married",
    "Withholding Allowance": "10",
    "Additional Withholding": "10.10",
    "NYC Withholding Allowance": "20",
    "NYC Additional Withholding": "14.00"
  }
}
```

In this example, **NYC Withholding Allowance** and **NYC Additional Withholding** are required because the employee is located in New York.

***

### 🔹 Miscellaneous State Taxes

Miscellaneous state taxes apply only in certain cases and are configured per employee. Rollfi currently supports **Washington L\&I** taxes through this flow. Follow the steps below to add them:

1. Retrieve the required fields for miscellaneous state tax setup using\
   [getEmployeeMiscellaneousStateTaxFormFields](https://developer.rollfi.xyz/api-reference/reports/getEmployeeMiscellaneousStateTaxFormFields).

2. Add the employee’s miscellaneous state tax information during onboarding using\
   [addEmployeeMiscellaneousStateTax](https://developer.rollfi.xyz/api-reference/useronboarding/addEmployeeMiscellaneousStateTax).\
   This ensures the tax is available for payroll processing.

```json theme={null}
{
  "method": "addEmployeeMiscellaneousStateTax",
  "companyId": "7440E812-C699-4A94-AE14-A4B788D83299",
  "userId": "98CCB6CF-08DD-4C17-A367-B339CD5526CD",
  "employeeMiscellaneousStateTax": {
    "CompositeRate": "5",
    "RiskClassName": "Painter",
    "RiskClassCode": "121212",
    "PayrollDeductionRate": "4"
  }
}
```

> To verify the miscellaneous state taxes were added correctly, or to view miscellaneous state tax that have already been added, use the [getUser](https://developer.rollfi.xyz/api-reference/reports/getUser) API.

3. When preparing payroll, retrieve the employee’s miscellaneous state tax data using\
   [getEmployeeMiscellaneousStateTaxforPayroll](https://developer.rollfi.xyz/api-reference/reports/getEmployeeMiscellaneousStateTaxforPayroll).\
   The response will resemble the following:

```json theme={null}
{
  "miscellaneousStateTaxes": [
    {
      "stateCode": "WA",
      "taxName": "Washington L&I",
      "taxDetails": [
        {
          "riskClassName": "Electrician",
          "noOfHours": 0
        }
      ]
    }
  ]
}
```

4. Add the taxes to payroll using\
   [importRegularPayrollData](https://developer.rollfi.xyz/api-reference/payroll/importRegularPayrollData)\
   or [importRegularDifferentialPayrollData](https://developer.rollfi.xyz/api-reference/payroll/importRegularDifferentialPayrollData) if the employee has differential pay.\
   Include the miscellaneous state tax details returned in the previous step.

> **Note:** You must update the `noOfHours` value when importing payroll data so miscellaneous state taxes can be calculated correctly. For the Washington L\&I example above, this represents the number of hours the employee worked in the specified risk class.

***