{"openapi":"3.1.0","info":{"title":"iTensia Tax Data API","version":"2026-10-01","description":"Effective-dated US federal and state payroll tax rules. Every value is extracted from an official government source, verified, and approved by two reviewers before publication. Rates are decimal fractions as strings (\"0.062\" = 6.2%); money is US dollars as strings (\"176100.00\")."},"servers":[{"url":"https://tax-api.itensiahr.com/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Rates","description":"Taxes that apply to a paycheck"},{"name":"Reference","description":"Jurisdictions and tax programs"},{"name":"Versions","description":"Immutable published versions and the change feed"},{"name":"System","description":"Status and spec (no key needed)"}],"paths":{"/rates/lookup":{"get":{"tags":["Rates"],"operationId":"lookupRates","summary":"Look up every tax for a paycheck","description":"Returns all federal taxes plus the work state's taxes (and the residence state's income tax withholding if different) in force on `pay_date`. Taxes without a published version for that date are listed in `meta.unavailable` — never silently omitted.","parameters":[{"name":"work_state","in":"query","required":true,"schema":{"type":"string","example":"CA"},"description":"Two-letter state where the work is performed"},{"name":"pay_date","in":"query","schema":{"type":"string","format":"date","example":"2026-10-15"},"description":"Defaults to today (UTC)"},{"name":"residence_state","in":"query","schema":{"type":"string","example":"NV"},"description":"Employee's resident state, if different"},{"name":"filing_status","in":"query","schema":{"type":"string","example":"single"},"description":"Filters per-status values and brackets (single, married_joint, head_of_household, …)"},{"name":"include","in":"query","schema":{"type":"string","default":"federal,state"},"description":"Comma list: federal, state"},{"name":"as_of","in":"query","schema":{"type":"string","format":"date-time"},"description":"Answer exactly as the API would have at this moment (Growth plan and up)"}],"responses":{"200":{"description":"Taxes in force","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResponse"}}}},"400":{"description":"Invalid parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Trial ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account suspended, or the feature is not in your plan (PLAN_FEATURE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (RATE_LIMITED) or monthly quota (QUOTA_EXCEEDED) reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jurisdictions":{"get":{"tags":["Reference"],"operationId":"listJurisdictions","summary":"List jurisdictions and their tax programs","responses":{"200":{"description":"Jurisdictions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Jurisdiction"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Invalid parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Trial ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account suspended, or the feature is not in your plan (PLAN_FEATURE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (RATE_LIMITED) or monthly quota (QUOTA_EXCEEDED) reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jurisdictions/{code}":{"get":{"tags":["Reference"],"operationId":"getJurisdiction","summary":"All taxes in force for one jurisdiction","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CA"},"description":"US for federal, or a state code"},{"name":"date","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Jurisdiction taxes"},"400":{"description":"Invalid parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Trial ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account suspended, or the feature is not in your plan (PLAN_FEATURE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (RATE_LIMITED) or monthly quota (QUOTA_EXCEEDED) reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/versions/{id}":{"get":{"tags":["Versions"],"operationId":"getVersion","summary":"One published (or superseded) version, by id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Version","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tax"}}}}}},"400":{"description":"Invalid parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Trial ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account suspended, or the feature is not in your plan (PLAN_FEATURE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (RATE_LIMITED) or monthly quota (QUOTA_EXCEEDED) reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/changes":{"get":{"tags":["Versions"],"operationId":"listChanges","summary":"Change feed (Starter plan and up)","description":"Versions published or superseded since a timestamp. Poll it daily, or after each payroll run.","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Defaults to 30 days ago"}],"responses":{"200":{"description":"Changes"},"400":{"description":"Invalid parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Trial ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account suspended, or the feature is not in your plan (PLAN_FEATURE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (RATE_LIMITED) or monthly quota (QUOTA_EXCEEDED) reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/status":{"get":{"tags":["System"],"operationId":"status","summary":"Service status and data freshness","security":[],"responses":{"200":{"description":"Status"}}}},"/openapi.json":{"get":{"tags":["System"],"operationId":"openapi","summary":"This specification","security":[],"responses":{"200":{"description":"OpenAPI document"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer itx_live_…` (the `x-api-key` header is also accepted)"}},"schemas":{"Meta":{"type":"object","properties":{"request_id":{"type":"string","example":"req_7hQ2kLp0aX1c"},"processing_ms":{"type":"integer","example":18},"api_version":{"type":"string","example":"2026-10-01"}}},"Bracket":{"type":"object","properties":{"table":{"type":"string","example":"standard_annual"},"filing_status":{"type":"string","example":"single"},"period":{"type":"string","example":"annual"},"over":{"type":"string","example":"0.00"},"not_over":{"type":["string","null"],"example":"11925.00"},"rate":{"type":"string","example":"0.1"},"base_tax":{"type":"string","example":"0.00"}}},"Tax":{"type":"object","properties":{"tax_code":{"type":"string","example":"US-CA:SUI"},"tax_type":{"type":"string","example":"state_unemployment"},"name":{"type":"string","example":"California unemployment insurance"},"jurisdiction":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"level":{"type":"string","enum":["federal","state"]}}},"applies_to":{"type":"string","enum":["federal","work","residence"]},"rate_structure":{"type":"string","example":"wage_base_capped_rate"},"effective_from":{"type":"string","format":"date"},"effective_to":{"type":["string","null"],"format":"date","description":"Exclusive end: the first date this version no longer applies. null while open-ended."},"tax_year":{"type":"integer"},"parameters":{"type":"object","additionalProperties":true,"example":{"wage_base":"7000.00","new_employer_rate":"0.034"}},"brackets":{"type":"array","items":{"$ref":"#/components/schemas/Bracket"}},"notes":{"type":["string","null"]},"version":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"published_at":{"type":"string","format":"date-time"},"content_sha256":{"type":"string"}}},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"sha256":{"type":"string"}}}}}},"LookupResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"work_state":{"type":"string","example":"CA"},"residence_state":{"type":["string","null"]},"pay_date":{"type":"string","format":"date"},"as_of":{"type":"string","format":"date-time"},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}}}},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"unavailable":{"type":"array","items":{"type":"object","properties":{"tax_code":{"type":"string"},"name":{"type":"string"},"reason":{"type":"string"}}}}}}]}}},"Jurisdiction":{"type":"object","properties":{"code":{"type":"string","example":"US-CA"},"state":{"type":["string","null"],"example":"CA"},"name":{"type":"string"},"level":{"type":"string"},"has_wage_income_tax":{"type":"boolean"},"taxes":{"type":"array","items":{"type":"object","properties":{"tax_code":{"type":"string"},"tax_type":{"type":"string"},"name":{"type":"string"}}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"QUOTA_EXCEEDED"},"message":{"type":"string"},"request_id":{"type":"string"},"docs_url":{"type":"string"}}}}}}}}