Taxwithholding data model

Updated:

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

View field support, webhooks, and list parameters for each integration on the Supported Integrations page.

FieldTypeRequiredDescription
idstringNo
created_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
user_idstringNoemployee ID (reference to HrisEmployee)
company_idstringNo(reference to HrisCompany)
countrystringNoISO 3166-1 alpha-2 country code of the taxing authority (eg. US, CA)
jurisdiction_typeenumNoValues: FEDERAL, STATE, LOCAL
jurisdictionstringNoregion/locality code within the country (eg. CA, NY, NY-NYC); empty for FEDERAL
is_residentbooleanNotrue for the resident (home) jurisdiction, false for a work-only jurisdiction
formenumNowithholding form the values come from (eg. 2020+ W-4) Values: W4_2020, W4_LEGACY, STATE_FORM, TD1, OTHER
filing_statusenumNoValues: SINGLE, MARRIED_JOINTLY, MARRIED_SEPARATELY, HEAD_OF_HOUSEHOLD, QUALIFYING_SURVIVOR, OTHER
tax_codestringNojurisdiction-specific tax code (eg. UK 1257L)
allowancesnumberNowithholding allowances (pre-2020 W-4 and most state forms)
claim_amountnumberNodollar exemption / claim amount (eg. Canada TD1, Illinois IL-W-4)
has_multiple_jobsbooleanNoW-4 step 2: multiple jobs or spouse works
dependents_amountnumberNoW-4 step 3: dependents credit amount
other_income_amountnumberNoW-4 step 4a: other income amount
other_deductions_amountnumberNoW-4 step 4b: deductions amount
extra_withholding_amountnumberNoW-4 step 4c: additional amount withheld each pay period
extra_withholding_percentnumberNoadditional percentage of wages withheld each pay period
override_typeenumNoreplaces the calculated withholding with a flat amount or percentage Values: NONE, FIXED_AMOUNT, PERCENT
override_amountnumberNomoney (FIXED_AMOUNT) or percentage (PERCENT) withheld instead of the calculated amount
is_exemptbooleanNoemployee claims exemption from withholding in this jurisdiction
effective_atstring (date-time)Nodate these withholding settings take effect (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
metadataHrisMetadata[]No
metadata[].idstringNoThe ID of the custom field definition (from the metadata/metadata endpoint).
metadata[].valueobjectNoThe 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[].namespacestringNo
metadata[].formatenumNoThe 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_dataobjectNo
metadata[].slugstringNoThe 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

Zod
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]
Are we missing anything? Let us know
Was this page helpful?