Endpoints

Rates lookup

Every federal and state tax that applies to one paycheck, as in force on the pay date.

GET/v1/rates/lookup

Query parameters

Parameter	Type	Description
`work_state`required	string	Two-letter state where the work is performed, e.g. `CA`. `DC` is accepted.
`pay_date`	YYYY-MM-DD	The check date. Rules in force on this date are returned. Defaults to today (UTC).
`residence_state`	string	Employee's home state, if different. Adds that state's income tax withholding only; unemployment and disability follow the work state.
`filing_status`	string	Narrow status-specific values to one status: `single`, `married_joint`, `married_separate`, `head_of_household`, or a state's own status name in snake_case.
`include`	string	Comma-separated: `federal`, `state`. Default `federal,state`.
`as_of`	ISO 8601 timestamp	Answer as the API would have at this moment. Growth plan and above. See versioning.

camelCase aliases (workState, payDate, …) are accepted for compatibility.

Example

bash

curl "https://tax-api-dev.itensiahr.com/v1/rates/lookup?work_state=NY&residence_state=NJ&pay_date=2025-10-15&filing_status=single" \
  -H "Authorization: Bearer $ITX_API_KEY"

Response (abridged, illustrative)

{
  "data": {
    "work_state": "CA",
    "pay_date": "2025-10-15",
    "taxes": [
      {
        "tax_code": "US:SS",
        "tax_type": "federal_social_security",
        "rate_structure": "wage_base_capped_rate",
        "effective_from": "2025-01-01",
        "parameters": {
          "employee_rate": "0.062",
          "employer_rate": "0.062",
          "wage_base": "176100.00"
        },
        "version": { "number": 1, "published_at": "2025-01-02T16:04:11Z" },
        "sources": [{ "url": "https://www.ssa.gov/oact/cola/cbb.html", "sha256": "9f2c…" }]
      },
      {
        "tax_code": "US-CA:SUI",
        "tax_type": "state_unemployment",
        "applies_to": "work",
        "parameters": {
          "wage_base": "7000.00",
          "new_employer_rate": "0.034"
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_7hQ2kLp0aX1c",
    "processing_ms": 21,
    "unavailable": []
  }
}

The tax object

Field	Type	Description
`tax_code`	string	Stable id: jurisdiction and short type, e.g. `US:FIT`, `US-CA:SUI`.
`tax_type`	string	e.g. `federal_income_tax_withholding`, `state_unemployment`, `state_disability`, `state_paid_family_leave`.
`applies_to`	string	`federal`, `work` or `residence` — why this tax is in the response.
`rate_structure`	string	`flat_rate`, `wage_base_capped_rate`, `graduated_brackets`, `flat_amount` or `no_tax`.
`effective_from / effective_to`	date \| null	The window this version applies to. effective_to is exclusive — the first date it no longer applies — and null while open-ended.
`parameters`	object	Named values. Rates are decimal-fraction strings, money is dollar strings, counts are integers. Values that differ by filing status are objects keyed by status unless you passed `filing_status`.
`brackets`	array	For graduated taxes: `table`, `filing_status`, `period`, `over`, `not_over`, `rate`, `base_tax`.
`version`	object	`id`, `number`, `published_at`, `superseded_at`, `content_sha256`.
`sources`	array	Official documents this version was read from, each with the SHA-256 of the copy we read.

When something isn't published yet

If a tax applies to the request but no approved version covers the pay date, it appears in meta.unavailable with a reason, rather than being silently omitted:

json

"meta": {
  "unavailable": [
    { "tax_code": "US-NY:PFML", "name": "New York Paid Family Leave", "reason": "no_published_version_for_pay_date" }
  ]
}

Treat a non-empty unavailable list as a signal to hold or flag the payroll run — don't assume a missing tax is zero.

Precision

Never parse rates or amounts as binary floats. Use decimal.js or big.js in JavaScript, Decimal in Python, or BigDecimal in Java/Kotlin.

PreviousAuthentication NextJurisdictions