---
updatedAt: 2026-04-27T15:52:51.000Z
agentTools:
  siteIndex: https://developer.paylocity.com/llms.txt
  projectIndex: https://developer.paylocity.com/integrations/llms.txt
---

# Upsert Primary State Tax

Sends new or updated employee primary state tax information directly to Paylocity Payroll/HR solution.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "WebLink API",
    "description": "For documentation about this API, please visit https://developer.paylocity.com/integrations/reference/weblink-overview",
    "contact": {
      "email": "webservices@paylocity.com"
    },
    "version": "v2"
  },
  "servers": [
    {
      "url": "https://dc1demogw.paylocity.com/api"
    }
  ],
  "paths": {
    "/v2/companies/{companyId}/employees/{employeeId}/primaryStateTax": {
      "put": {
        "tags": [
          "Primary State Tax"
        ],
        "summary": "Upsert Primary State Tax",
        "description": "Sends new or updated employee primary state tax information directly to Paylocity Payroll/HR solution.",
        "x-explorer-enabled": false,
        "operationId": "Add or update primary state tax",
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "description": "The Paylocity Company Identifier. This is the unique value provided by Paylocity to each specific Payroll Entity.\r\n                **Allowable Values:**\r\n                9 char max",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "employeeId",
            "in": "path",
            "description": "The Paylocity Employee ID. This is a unique value per Paylocity Company ID.\r\n**Allowable Values:**\r\n10 char max",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Primary State Tax Model",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/stateTax"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successfully added or updated",
            "content": {}
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/error"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {}
          },
          "403": {
            "description": "Forbidden",
            "content": {}
          },
          "429": {
            "description": "Too Many Requests",
            "content": {}
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/error"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "paylocity_auth": [
              "WebLinkAPI"
            ]
          }
        ],
        "x-codegen-request-body-name": "json"
      }
    }
  },
  "components": {
    "schemas": {
      "error": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "The name of the field, or property in the request message that contains an error."
          },
          "message": {
            "type": "string",
            "description": "The error message."
          },
          "options": {
            "type": "array",
            "description": "A list of options associated with this error. These options may indicate valid values for the field, or property that contains an error.",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "description": "The code associated with this option."
                },
                "description": {
                  "type": "string",
                  "description": "The description of the option."
                }
              },
              "description": "The error option model"
            }
          },
          "path": {
            "type": "string",
            "description": "The JSON path of the field, or property, that contains an error in the request message."
          }
        },
        "description": "The error model"
      },
      "stateTax": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "number",
            "description": "State tax code.<br  /> Max length: 50"
          },
          "deductionsAmount": {
            "type": "number",
            "description": "Box 4(b) on form W4 (year 2020 or later): Deductions amount. <br  />Decimal (12,2)"
          },
          "dependentsAmount": {
            "type": "number",
            "description": "Box 3 on form W4 (year 2020 or later): Total dependents amount. <br  />Decimal (12,2)"
          },
          "exemptions": {
            "type": "number",
            "description": "State tax exemptions value.<br  />Decimal (12,2)"
          },
          "exemptions2": {
            "type": "number",
            "description": "State tax exemptions 2 value.<br  />Decimal (12,2)"
          },
          "filingStatus": {
            "type": "string",
            "description": "Employee state tax filing status. Common values are *S* (Single), *M* (Married).<br  />Max length: 50"
          },
          "higherRate": {
            "type": "boolean",
            "description": "Box 2(c) on form W4 (year 2020 or later): Multiple Jobs or Spouse Works. <br  />Boolean"
          },
          "otherIncomeAmount": {
            "type": "number",
            "description": "Box 4(a) on form W4 (year 2020 or later): Other income amount. <br  />Decimal (12,2)"
          },
          "percentage": {
            "type": "number",
            "description": "State Tax percentage. <br  />Decimal (12,2)"
          },
          "specialCheckCalc": {
            "type": "string",
            "description": "Supplemental check calculation code. Common values are *Blocked* (Taxes blocked on Supplemental checks), *Supp* (Use supplemental Tax Rate-Code). <br  />Max length: 10"
          },
          "taxCalculationCode": {
            "type": "string",
            "description": "Tax calculation code. Common values are *F* (Flat), *P* (Percentage), *FDFP* (Flat Dollar Amount plus Fixed Percentage). <br  />Max length: 10"
          },
          "taxCode": {
            "type": "string",
            "description": "State tax code.<br  /> Max length: 50"
          },
          "w4FormYear": {
            "type": "integer",
            "description": "The state W4 form year <br  />Integer"
          }
        },
        "additionalProperties": false,
        "description": "The State Tax model"
      }
    },
    "securitySchemes": {
      "paylocity_auth": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.paylocity.com/IdentityServer/connect/token",
            "scopes": {
              "WebLinkAPI": "Web Link Api"
            }
          }
        }
      }
    }
  },
  "x-original-swagger-version": "2.0"
}
```