---
title: "Taxwithholding data model"
url: "https://docs.unified.to/hris/taxwithholding/model"
description: "The Taxwithholding data model object in Unified's Taxwithholding API: 25 fields, including created_at, updated_at and user_id, with types and enum values."
date: "2026-11-16T23:13:16.218Z"
updated: "2026-11-16T23:13:16.218Z"
---
# Taxwithholding data model

Updated: November 16, 2026

Employee tax withholding settings for one jurisdiction (eg. W-4)

 View field support, webhooks, and list parameters for each integration on the [Supported Integrations](https://docs.unified.to/hris/integrations.md) page. 

| Field                       | Type               | Required | Description                                                                                                                                                                                                                                              |
| --------------------------- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                          | string             | No       |                                                                                                                                                                                                                                                          |
| created\_at                 | string (date-time) | No       | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                                 |
| updated\_at                 | string (date-time) | No       | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                                 |
| user\_id                    | string             | No       | employee ID (reference to HrisEmployee)                                                                                                                                                                                                                  |
| company\_id                 | string             | No       | (reference to HrisCompany)                                                                                                                                                                                                                               |
| country                     | string             | No       | ISO 3166-1 alpha-2 country code of the taxing authority (eg. US, CA)                                                                                                                                                                                     |
| jurisdiction\_type          | enum               | No       | Values: FEDERAL, STATE, LOCAL                                                                                                                                                                                                                            |
| jurisdiction                | string             | No       | region/locality code within the country (eg. CA, NY, NY-NYC); empty for FEDERAL                                                                                                                                                                          |
| is\_resident                | boolean            | No       | true for the resident (home) jurisdiction, false for a work-only jurisdiction                                                                                                                                                                            |
| form                        | enum               | No       | withholding form the values come from (eg. 2020+ W-4) Values: W4\_2020, W4\_LEGACY, STATE\_FORM, TD1, OTHER                                                                                                                                              |
| filing\_status              | enum               | No       | Values: SINGLE, MARRIED\_JOINTLY, MARRIED\_SEPARATELY, HEAD\_OF\_HOUSEHOLD, QUALIFYING\_SURVIVOR, OTHER                                                                                                                                                  |
| tax\_code                   | string             | No       | jurisdiction-specific tax code (eg. UK 1257L)                                                                                                                                                                                                            |
| allowances                  | number             | No       | withholding allowances (pre-2020 W-4 and most state forms)                                                                                                                                                                                               |
| claim\_amount               | number             | No       | dollar exemption / claim amount (eg. Canada TD1, Illinois IL-W-4)                                                                                                                                                                                        |
| has\_multiple\_jobs         | boolean            | No       | W-4 step 2: multiple jobs or spouse works                                                                                                                                                                                                                |
| dependents\_amount          | number             | No       | W-4 step 3: dependents credit amount                                                                                                                                                                                                                     |
| other\_income\_amount       | number             | No       | W-4 step 4a: other income amount                                                                                                                                                                                                                         |
| other\_deductions\_amount   | number             | No       | W-4 step 4b: deductions amount                                                                                                                                                                                                                           |
| extra\_withholding\_amount  | number             | No       | W-4 step 4c: additional amount withheld each pay period                                                                                                                                                                                                  |
| extra\_withholding\_percent | number             | No       | additional percentage of wages withheld each pay period                                                                                                                                                                                                  |
| override\_type              | enum               | No       | replaces the calculated withholding with a flat amount or percentage Values: NONE, FIXED\_AMOUNT, PERCENT                                                                                                                                                |
| override\_amount            | number             | No       | money (FIXED\_AMOUNT) or percentage (PERCENT) withheld instead of the calculated amount                                                                                                                                                                  |
| is\_exempt                  | boolean            | No       | employee claims exemption from withholding in this jurisdiction                                                                                                                                                                                          |
| effective\_at               | string (date-time) | No       | date these withholding settings take effect (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                     |
| metadata                    | HrisMetadata\[\]   | No       |                                                                                                                                                                                                                                                          |
| metadata\[\].id             | string             | No       | The ID of the custom field definition (from the metadata/metadata endpoint).                                                                                                                                                                             |
| metadata\[\].value          | object             | No       | The field's value, typed by format: DATE as ISO-8601 (YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ for date-times); NUMBER, PRICE and CURRENCY as a number; BOOLEAN and YES\_NO as true/false; MULTIPLE\_SELECT as an array of option values; otherwise a string. |
| metadata\[\].namespace      | string             | No       |                                                                                                                                                                                                                                                          |
| metadata\[\].format         | enum               | No       | The data type of the custom field, which determines how value is formatted. Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE\_SELECT, MULTIPLE\_SELECT, MEASUREMENT, PRICE, YES\_NO, CURRENCY, URL                                            |
| metadata\[\].extra\_data    | object             | No       |                                                                                                                                                                                                                                                          |
| metadata\[\].slug           | string             | No       | The integration's API name (key) of an existing custom field. List valid slugs for this object with the metadata/metadata endpoint; unknown slugs are rejected by the integration.                                                                       |

## TypeScript

```typescript
export type HrisTaxwithholding = {
	id?: string;
	created_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	updated_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	user_id?: string; // employee ID (reference to HrisEmployee)
	company_id?: string; // (reference to HrisCompany)
	country?: string; // ISO 3166-1 alpha-2 country code of the taxing authority (eg. US, CA)
	jurisdiction_type?: 'FEDERAL' | 'STATE' | 'LOCAL';
	jurisdiction?: string; // region/locality code within the country (eg. CA, NY, NY-NYC); empty for FEDERAL
	is_resident?: boolean; // true for the resident (home) jurisdiction, false for a work-only jurisdiction
	form?: 'W4_2020' | 'W4_LEGACY' | 'STATE_FORM' | 'TD1' | 'OTHER'; // withholding form the values come from (eg. 2020+ W-4)
	filing_status?: 'SINGLE' | 'MARRIED_JOINTLY' | 'MARRIED_SEPARATELY' | 'HEAD_OF_HOUSEHOLD' | 'QUALIFYING_SURVIVOR' | 'OTHER';
	tax_code?: string; // jurisdiction-specific tax code (eg. UK 1257L)
	allowances?: number; // withholding allowances (pre-2020 W-4 and most state forms)
	claim_amount?: number; // dollar exemption / claim amount (eg. Canada TD1, Illinois IL-W-4)
	has_multiple_jobs?: boolean; // W-4 step 2: multiple jobs or spouse works
	dependents_amount?: number; // W-4 step 3: dependents credit amount
	other_income_amount?: number; // W-4 step 4a: other income amount
	other_deductions_amount?: number; // W-4 step 4b: deductions amount
	extra_withholding_amount?: number; // W-4 step 4c: additional amount withheld each pay period
	extra_withholding_percent?: number; // additional percentage of wages withheld each pay period
	override_type?: 'NONE' | 'FIXED_AMOUNT' | 'PERCENT'; // replaces the calculated withholding with a flat amount or percentage
	override_amount?: number; // money (FIXED_AMOUNT) or percentage (PERCENT) withheld instead of the calculated amount
	is_exempt?: boolean; // employee claims exemption from withholding in this jurisdiction
	effective_at?: string-time; // date these withholding settings take effect (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	metadata?: [];
	raw?: any;
} 
```

## Zod

```typescript
import { z } from 'zod';

export const ZodHrisTaxwithholding = z.object({
	id: z.string().optional(),
	created_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	updated_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	user_id: z.string().optional().describe("employee ID (reference to HrisEmployee)"),
	company_id: z.string().optional().describe("(reference to HrisCompany)"),
	country: z.string().optional().describe("ISO 3166-1 alpha-2 country code of the taxing authority (eg. US, CA)"),
	jurisdiction_type: z.enum("FEDERAL", "STATE", "LOCAL").optional(),
	jurisdiction: z.string().optional().describe("region/locality code within the country (eg. CA, NY, NY-NYC); empty for FEDERAL"),
	is_resident: z.boolean().optional().describe("true for the resident (home) jurisdiction, false for a work-only jurisdiction"),
	form: z.enum("W4_2020", "W4_LEGACY", "STATE_FORM", "TD1", "OTHER").optional().describe("withholding form the values come from (eg. 2020+ W-4)"),
	filing_status: z.enum("SINGLE", "MARRIED_JOINTLY", "MARRIED_SEPARATELY", "HEAD_OF_HOUSEHOLD", "QUALIFYING_SURVIVOR", "OTHER").optional(),
	tax_code: z.string().optional().describe("jurisdiction-specific tax code (eg. UK 1257L)"),
	allowances: z.number().optional().describe("withholding allowances (pre-2020 W-4 and most state forms)"),
	claim_amount: z.number().optional().describe("dollar exemption / claim amount (eg. Canada TD1, Illinois IL-W-4)"),
	has_multiple_jobs: z.boolean().optional().describe("W-4 step 2: multiple jobs or spouse works"),
	dependents_amount: z.number().optional().describe("W-4 step 3: dependents credit amount"),
	other_income_amount: z.number().optional().describe("W-4 step 4a: other income amount"),
	other_deductions_amount: z.number().optional().describe("W-4 step 4b: deductions amount"),
	extra_withholding_amount: z.number().optional().describe("W-4 step 4c: additional amount withheld each pay period"),
	extra_withholding_percent: z.number().optional().describe("additional percentage of wages withheld each pay period"),
	override_type: z.enum("NONE", "FIXED_AMOUNT", "PERCENT").optional().describe("replaces the calculated withholding with a flat amount or percentage"),
	override_amount: z.number().optional().describe("money (FIXED_AMOUNT) or percentage (PERCENT) withheld instead of the calculated amount"),
	is_exempt: z.boolean().optional().describe("employee claims exemption from withholding in this jurisdiction"),
	effective_at: z.string-time().optional().describe("date these withholding settings take effect (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	metadata: z.array().optional(),

});
```

## Python

```python
import dataclasses

@dataclasses.dataclass
class HrisTaxwithholdingJurisdiction_type(str, Enum):
	FEDERAL = 'FEDERAL'
	STATE = 'STATE'
	LOCAL = 'LOCAL'

@dataclasses.dataclass
class HrisTaxwithholdingForm(str, Enum):
	W4_2020 = 'W4_2020'
	W4_LEGACY = 'W4_LEGACY'
	STATE_FORM = 'STATE_FORM'
	TD1 = 'TD1'
	OTHER = 'OTHER'

@dataclasses.dataclass
class HrisTaxwithholdingFiling_status(str, Enum):
	SINGLE = 'SINGLE'
	MARRIED_JOINTLY = 'MARRIED_JOINTLY'
	MARRIED_SEPARATELY = 'MARRIED_SEPARATELY'
	HEAD_OF_HOUSEHOLD = 'HEAD_OF_HOUSEHOLD'
	QUALIFYING_SURVIVOR = 'QUALIFYING_SURVIVOR'
	OTHER = 'OTHER'

@dataclasses.dataclass
class HrisTaxwithholdingOverride_type(str, Enum):
	NONE = 'NONE'
	FIXED_AMOUNT = 'FIXED_AMOUNT'
	PERCENT = 'PERCENT'

@dataclasses.dataclass
class HrisTaxwithholding:
	id: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	created_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	updated_at: Optional[str]
	"""employee ID (reference to HrisEmployee)"""
	user_id: Optional[str]
	"""(reference to HrisCompany)"""
	company_id: Optional[str]
	"""ISO 3166-1 alpha-2 country code of the taxing authority (eg. US, CA)"""
	country: Optional[str]
	jurisdiction_type: Optional[HrisTaxwithholdingJurisdiction_type]
	"""region/locality code within the country (eg. CA, NY, NY-NYC); empty for FEDERAL"""
	jurisdiction: Optional[str]
	"""true for the resident (home) jurisdiction, false for a work-only jurisdiction"""
	is_resident: Optional[bool]
	"""withholding form the values come from (eg. 2020+ W-4)"""
	form: Optional[HrisTaxwithholdingForm]
	filing_status: Optional[HrisTaxwithholdingFiling_status]
	"""jurisdiction-specific tax code (eg. UK 1257L)"""
	tax_code: Optional[str]
	"""withholding allowances (pre-2020 W-4 and most state forms)"""
	allowances: Optional[int]
	"""dollar exemption / claim amount (eg. Canada TD1, Illinois IL-W-4)"""
	claim_amount: Optional[int]
	"""W-4 step 2: multiple jobs or spouse works"""
	has_multiple_jobs: Optional[bool]
	"""W-4 step 3: dependents credit amount"""
	dependents_amount: Optional[int]
	"""W-4 step 4a: other income amount"""
	other_income_amount: Optional[int]
	"""W-4 step 4b: deductions amount"""
	other_deductions_amount: Optional[int]
	"""W-4 step 4c: additional amount withheld each pay period"""
	extra_withholding_amount: Optional[int]
	"""additional percentage of wages withheld each pay period"""
	extra_withholding_percent: Optional[int]
	"""replaces the calculated withholding with a flat amount or percentage"""
	override_type: Optional[HrisTaxwithholdingOverride_type]
	"""money (FIXED_AMOUNT) or percentage (PERCENT) withheld instead of the calculated amount"""
	override_amount: Optional[int]
	"""employee claims exemption from withholding in this jurisdiction"""
	is_exempt: Optional[bool]
	"""date these withholding settings take effect (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	effective_at: Optional[str]
	metadata: Optional[PropertyHrisTaxwithholdingMetadata]

```
