---
title: "TaxWithholdingChangeRequest"
url: "https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84/schemas/TaxWithholdingChangeRequest"
---

> Full API specification: https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84.md

# TaxWithholdingChangeRequest

Request body for tax withholding change (POST `/bpm/v1/policies/{planCode}/{policyNumber}/parties/taxwithholding` and validation). Extends transaction case fields with effective date and one or more withholding instruction lines.

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Zinnia Policy Transactions API.
  version: 1.0.8
servers:
  - url: https://dev.api.zinnia.io
    description: DEV Environment
  - url: https://qa.api.zinnia.io
    description: QA Environment
components:
  schemas:
    TaxWithholdingInstructions:
      type: object
      properties:
        partyId:
          type: string
          example: Party_PI_1
          description: Impacted Party in the event of financial transaction
        taxWithholdingType:
          $ref: "#/components/schemas/TaxWithholdingType"
        taxRateToUse:
          $ref: "#/components/schemas/TaxRateToUse"
        filingStatus:
          $ref: "#/components/schemas/FilingStatus"
        dollar:
          type: number
          format: double
          example: 10
          description: Requested amount value
        percentage:
          type: number
          format: double
          example: 50
          description: Requested percentage value
        exemptions:
          type: number
          format: int32
          example: 0
          description: Requested exemptions value
        taxJurisdiction:
          type: string
          example: USA
          description: Requested amount value
      required:
        - partyId
        - taxWithholdingType
        - taxRateToUse
    TaxWithholdingType:
      type: string
      enum:
        - FEDERAL
        - STATE
        - NRA
        - BACKUP
    TaxRateToUse:
      type: string
      enum:
        - NOWITHHOLDINGELECTED
        - USEVALUESENTERED
        - NOWITHHOLDINGALLOWED
        - USEDEFAULTTABLE
        - ADDITIONALWITHHOLDING
      description: How tax rate should be applied for withholding
    FilingStatus:
      type: string
      enum:
        - SINGLE
        - DOMESTICPARTNERSHIP
        - DEFAULT
        - MARRIED
        - HEADOFHOUSEHOLD
        - MARRIEDFILINGSEPARATELY
        - WIDOWED
        - DIVORCED
    TaxWithholdingChangeRequest:
      type: object
      description: >
        Request body for tax withholding change (POST
        `/bpm/v1/policies/{planCode}/{policyNumber}/parties/taxwithholding`

        and validation). Extends transaction case fields with effective date and
        one or more withholding instruction lines.
      properties:
        planCode:
          type: string
          example: EVIU101
          description: Plan code (may duplicate path parameter)
        policyNumber:
          type: string
          example: EVIUL7RED012
          description: Policy number (may duplicate path parameter)
        effectiveDate:
          type: string
          format: date
          pattern: ([0-9]{4})-([0-9]{2})-([0-9]{2})
          example: 2026-06-17
          description: Effective date for the tax withholding change
        correlationId:
          type: string
          format: uuid
          example: e3bdb22b-790f-4357-ae60-42cdb0ff0d12
          description: The unique ID to track transaction request across all systems
        carrierId:
          type: string
          example: FNWL
          description: Carrier identifier
        caseId:
          type: string
          example: CA0000007389
          description: Zinnia Live Case ID
        taxWithholdingInstructions:
          type: array
          minItems: 1
          description: Tax withholding instruction lines for the request
          items:
            $ref: "#/components/schemas/TaxWithholdingInstructions"
      required:
        - effectiveDate
        - taxWithholdingInstructions
```