---
title: "State income tax (all 50 states + DC)"
method: POST
path: "/v1/tax/state-income"
tags: ["Tax"]
---

# State income tax (all 50 states + DC)

`POST /v1/tax/state-income`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/tax/state-income`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Computes state income tax for all 50 states + DC: the nine no-income-tax states ($0), the flat-rate states (single rate), and the graduated states with full brackets and state standard deductions (incl. the CA 1% MHSA and MA 4% millionaire surtaxes, and 0%% floors in ND/SC/DE). Complements the federal tax/estimate engine. v1 covers tax year 2025. Optional pension_income (generic qualified pension/401k/403b/IRA) applies each state's 2025 retirement-income exclusion — full exemption, fixed dollar caps, AGI phase-outs, or NJ/CT tiers — gated by age. Social Security is handled separately. Does not model flat states' own standard deductions. Deterministic.

## Request body

- StateTaxRequest
  - `state` string, required: 2-letter code or DC. All 50 states + DC covered (2025).
  - `tax_year` 2025, required
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `state_taxable_income` number, required: Non-SS, non-pension income, before the state standard deduction.
  - `social_security_income` number: Added to the base only for the 9 states that tax SS; the other 41 + DC exempt it.
  - `pension_income` number: Optional. Generic qualified retirement income (private pension / 401k / 403b / traditional IRA). The state's 2025 exclusion is applied; the taxable remainder is added to the base.
  - `age` integer: Optional. Gates age-conditioned pension exclusions (e.g. GA 62/65, NY 59½, IA 55).

## Response `200`

State tax

- StateTaxResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` StateTaxRequest
    - `state` string, required: 2-letter code or DC. All 50 states + DC covered (2025).
    - `tax_year` 2025, required
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `state_taxable_income` number, required: Non-SS, non-pension income, before the state standard deduction.
    - `social_security_income` number: Added to the base only for the 9 states that tax SS; the other 41 + DC exempt it.
    - `pension_income` number: Optional. Generic qualified retirement income (private pension / 401k / 403b / traditional IRA). The state's 2025 exclusion is applied; the taxable remainder is added to the base.
    - `age` integer: Optional. Gates age-conditioned pension exclusions (e.g. GA 62/65, NY 59½, IA 55).
  - `result` object
    - `state` string
    - `kind` 'none' | 'flat' | 'graduated'
    - `taxable_income` number: After the state standard deduction (where modeled).
    - `state_tax` number
    - `effective_rate` number
    - `marginal_rate` number
    - `social_security_taxed` boolean: Whether this state taxes Social Security benefits.
    - `pension_excluded` number: Portion of pension_income the state excludes.
    - `pension_taxable` number: Pension_income remainder added to the taxable base.
  - `disclaimer` string

## Other responses

- `400`: Invalid request (incl. uncovered state)
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)