--- title: "Submit Tax Withholding Transaction" url: "https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84/operations/submitTaxWithholding1" --- > Full API specification: https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84.md # Submit Tax Withholding Transaction `POST` `/policy/v1/transactions/{planCode}/{policyNumber}/parties/taxwithholding` Operation ID: `submitTaxWithholding1` Submits a tax withholding change transaction for processing. ## Path parameters - `planCode` (string, required) - Plan Code - `policyNumber` (string, required) - Policy Number ## Request body (required) Content types: `application/json` ## Responses - `202` - Submit Transaction Successful - `400` - Rules and Transaction Failure - `500` - Unexpected error occured, please check server logs ## 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 paths: /policy/v1/transactions/{planCode}/{policyNumber}/parties/taxwithholding: post: x-kong-plugin-pre-function: config: access: - > local path = kong.request.get_path() local new_path = path:gsub("^/policy/v1/transactions", "/bpm/v1/policies") kong.service.request.set_path(new_path) tags: - Non Financial Transactions summary: Submit Tax Withholding Transaction description: Submits a tax withholding change transaction for processing. operationId: submitTaxWithholding1 parameters: - name: planCode in: path required: true schema: type: string description: Plan Code example: EVIU101 - name: policyNumber in: path required: true schema: type: string description: Policy Number example: EVIUL7RED012 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TaxWithholdingChangeRequest" examples: taxWithholdingSubmitExample: summary: Tax withholding submit request example value: planCode: EVIU101 policyNumber: EVIUL7RED012 effectiveDate: 2026-06-17 correlationId: e3bdb22b-790f-4357-ae60-42cdb0ff0d12 carrierId: FNWL taxWithholdingInstructions: - partyId: "2314134" taxWithholdingType: FEDERAL filingStatus: MARRIED taxRateToUse: USEVALUESENTERED dollar: 0 percentage: 0 taxJurisdiction: USA responses: "202": description: Submit Transaction Successful content: application/json: schema: $ref: "#/components/schemas/TransactionAcceptedResponse" "400": description: Rules and Transaction Failure content: application/json: schema: $ref: "#/components/schemas/TransactionResponse" examples: failure: $ref: "#/components/examples/failureTransactionResponse" "500": description: Unexpected error occured, please check server logs security: - Auth0: [] security: - Auth0: [] components: schemas: 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 TransactionAcceptedResponse: type: object properties: correlationId: type: string example: 3a2a3435-2089-4b81-9959-e0d569ccf4f0 description: Unique identifier which used by every system to trace the request caseId: type: string example: CA0000369469 description: Zinnia Live Case ID caseStatus: type: string example: IN_PROGRESS description: Zinnia Live Case Status pdfId: type: string description: Identifier for the generated or associated PDF document (e.g. OnBase document number). Returned on systematic program setup and update submit when available. example: DOC-10004567 TransactionResponse: type: object properties: status: type: string enum: - success - failure error: type: array items: $ref: "#/components/schemas/Error" quoteResponse: type: object 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 Error: type: object properties: errorCode: type: string example: BPM.NM.002 description: This is the NIGO id generated by BPM system attribute: type: string error: type: string description: This is the error generated by BPM system resolution: type: string description: Resolution generated by BPM system to resolve the error 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 examples: failureTransactionResponse: value: status: failure validationResult: - errorCode: BPM.NM.005 attribute: null error: Amount request is invalid. resolution: Please check the One Time Premium Amount and submit the request again. - errorCode: BPM.NM.003 attribute: null error: Party information does not match with information in the Zahara system. resolution: Please validate the party information and submit the request again. securitySchemes: Auth0: type: openIdConnect openIdConnectUrl: https://login.qa.zinnia.com/.well-known/openid-configuration x-kong-security-openid-connect: config: run_on_preflight: true scopes_claim: - https://qa.api.zinnia.io/permissions audience_claim: - aud audience_required: - https://qa.api.zinnia.io client_id: - client_id auth_methods: - bearer enabled: true protocols: - grpc - grpcs - http - https ```