API documentation
Compute withholding for one paycheck
Federal income tax (IRS Pub 15-T, Worksheet 1A) and California PIT (EDD Method B) withholding for one pay period. Every line names the fact revisions it read and the official document and page they come from. The employee data is not stored.
REST: POST /v1/payroll/calculate MCP tool: payroll_calculate Needs an API key
Refusal codes
- input_invalid (400) The request does not match the action’s input schema.
- parameter_missing (400) A parameter the computation needs was not given.
- jurisdiction_unsupported (422) This tax or jurisdiction is not covered yet.
- table_not_effective (422) No reviewed fact is in force for this pay date.
- key_missing (401) This action needs an API key (Authorization: Bearer <key>).
- key_invalid (401) The API key is unknown, revoked or expired.
- rate_limited (429) Too many requests from this client; slow down.
- trial_exhausted (402) The trial key has used all of its included calls.
- quota_exhausted (402) The plan’s calls for this month are used; a larger plan or the next month opens more.
- plan_excludes_action (403) The account’s plan does not include this action.
Input (JSON Schema)
{
"type": "object",
"properties": {
"pay_date": {
"type": "string",
"format": "date"
},
"pay_frequency": {
"enum": [
"daily",
"weekly",
"biweekly",
"semimonthly",
"monthly",
"quarterly",
"semiannual",
"annual"
],
"type": "string"
},
"gross": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,2})?$"
},
"taxes": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "us_fit"
},
"w4": {
"type": "object",
"properties": {
"filing_status": {
"enum": [
"single",
"married_filing_jointly",
"head_of_household"
],
"type": "string"
},
"step2_checkbox": {
"type": "boolean",
"default": false
},
"step3_credits": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,2})?$",
"default": "0"
},
"step4a_other_income": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,2})?$",
"default": "0"
},
"step4b_deductions": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,2})?$",
"default": "0"
},
"step4c_extra_withholding": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,2})?$",
"default": "0"
},
"exempt": {
"type": "boolean",
"default": false
}
},
"required": [
"filing_status"
]
}
},
"required": [
"kind"
]
},
{
"type": "object",
"properties": {
"kind": {
"const": "us_ca_pit"
},
"de4": {
"type": "object",
"properties": {
"filing_status": {
"enum": [
"single",
"married",
"head_of_household"
],
"type": "string"
},
"regular_allowances": {
"type": "integer",
"minimum": 0,
"maximum": 99,
"default": 0
},
"estimated_deduction_allowances": {
"type": "integer",
"minimum": 0,
"maximum": 99,
"default": 0
},
"additional_withholding": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,2})?$",
"default": "0"
},
"exempt": {
"type": "boolean",
"default": false
}
},
"required": [
"filing_status"
]
},
"method": {
"enum": [
"annualized",
"period_table"
],
"type": "string",
"default": "annualized"
}
},
"required": [
"kind"
]
}
]
},
"minItems": 1,
"maxItems": 10
}
},
"required": [
"pay_date",
"pay_frequency",
"gross",
"taxes"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}