Taxwithholding data model
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.
| 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. |
Are we missing anything? Let us know
Was this page helpful?