Developer Documentation

A read-only U.S. federal, state, and local tax database. Every response carries a structured data/meta envelope with full verbatim primary-source citations, enabling fully-verifiable tax logic.

Open Interactive API ExplorerTry every endpoint live · no API key required

Quickstart

Fetch California's facts and filter to capital-gains rate facts. Code sample:

const res = await fetch('https://fedsalt.com/api/v1/jurisdictions/CA');
const { data } = await res.json();
const rates = data.facts.filter(f => f.category === 'rate');

Each fact has a machine-readable value (typed by valueType), a human-friendly display string, and inline statutory citations.

Response Envelope

Successful requests return { data, meta }. Failures return { error, meta } with a stable code (such as not_found, bad_request, or internal_error).

Example Success Payload

GET /api/v1/jurisdictions/HI

{
  "data": {
    "code": "HI",
    "name": "Hawaii",
    "level": "state",
    "facts": [
      {
        "jurisdiction": "HI",
        "category": "carryforward",
        "label": "Capital-loss carryforward limit",
        "display": "5 years (15 for a qualified high-tech business)",
        "value": 5,
        "valueType": "years",
        "citations": [
          {
            "id": "hi-cap-loss-carryforward-5yr",
            "jurisdiction": "HI",
            "authority": "HRS sec. 235-2.45(f)",
            "authorityType": "statute",
            "title": "Hawaii Capital Gains Tax: HRS 235",
            "quote": "the capital loss carryforward allowed by section 1212(a) shall be limited to five years; ...",
            "url": "https://files.hawaii.gov/tax/legal/hrs/hrs_235.pdf",
            "sourceDomain": "files.hawaii.gov",
            "taxYear": 2025,
            "asOf": "2026-06-19",
            "confidence": "high"
          }
        ]
      }
    ]
  },
  "meta": {
    "apiVersion": "v1",
    "schemaVersion": "1.6.0",
    "taxYear": 2025,
    "catalogAsOf": "2026-06-19",
    "source": "fed_salt catalog (primary .gov sources, verbatim-cited)"
  }
}

Example Error Payload

GET /api/v1/jurisdictions/ZZ

HTTP 404
{
  "error": {
    "code": "not_found",
    "message": "Unknown jurisdiction 'ZZ'.",
    "details": { "supported": ["HI", "WA", "US", "..."] }
  },
  "meta": {
    "apiVersion": "v1",
    "schemaVersion": "1.6.0",
    "taxYear": 2025,
    "catalogAsOf": "2026-06-19",
    "source": "fed_salt catalog (primary .gov sources, verbatim-cited)"
  }
}

Field Semantics

value and valueType

value represents the machine-interpretable number. Always use display for rendering to end users, and use value only for computational math.

valueType	Example	Semantic Meaning
rate	0.07	7% tax rate (rate, surcharge, character categories)
dollars	250000	$250,000 threshold or deduction (deduction, threshold categories)
years	5	5-year carry period (carryforward, carryback categories)
binary-exempt	1	1 = exempt/conforms, 0 = taxable/non-conforms (muni-instate, muni-outstate, treasury, qsbs-conformity categories)
exclusion-pct	0.40	40% of income excluded (dividend-qualified category)
code	2	non-negative integer enum; meaning set by category (qoz-conformity 0=decoupled/1=full/2=in-state, migration-loss-conformity 0=disallowed/1=full-conform/2=recalculate)
partial	null	state has a conditional or restricted conformity provision (qoz-conformity, qsbs-conformity categories)
none	null	no numeric value; provision is qualitative only (no-tax, conformity categories)

Confidence Levels

Citations carry verified confidence values: high = verbatim statutory text confirmed against the live official act. medium = agency guidance or form instructions. low = regulation pending update or needs re-verification.

Authority Types

Citations are typed: constitution, statute (codified law), session-law (uncodified enacted law), regulation (agency rule), dor-guidance (Dept of Revenue guidance), or form-instructions.

API Endpoints

GET/api/v1

Service index: discoverable list of endpoints.

GET/api/v1/catalog

Full catalog: all jurisdictions, facts, and citations in one call.

GET/api/v1/jurisdictions

List every catalogued jurisdiction (summary). Add ?category= to filter by fact category and get full detail.

GET/api/v1/jurisdictions/{code}

Facts + full citations for one jurisdiction. Unknown code returns 404 naming the supported set.

GET/api/v1/citations/{id}

Resolve a single citation by its stable slug ID. Makes any figure's provenance directly linkable.

GET/api/v1/health

Readiness probe: 200 with catalog count when healthy. Not cached.

GET/api/v1/openapi

OpenAPI 3.1 document for codegen.

Machine-readable contract: /api/v1/openapi (OpenAPI 3.1).

Bulk download: /api/v1/catalog (Full data payload).

Provenance Standard

Citations point only to government domains (machine-validated). Verbatim quotes are pulled directly from statutory texts; the asOf date records when it was read. Aggregators are used as cross-checks, never as the cited authority.

Schema Changelog

1.36.0: Entity-tax seam facts (batch 2). Illinois pass-through entity tax (35 ILCS 5/201(p)): availability, 4.95% entity rate, and the full owner credit. Additive; no removals.
1.35.0: Entity-tax seam facts (batch 1). Federal corporate income tax rate (IRC §11(b), 21%); California pass-through entity tax (R&TC §19900): availability, 9.3% entity rate, and the owner credit mechanism. New categories: corporate-rate, ptet-available, ptet-rate, ptet-credit-mechanism. Additive; no removals.
1.34.0: QSBS / §1202 seam facts. Corporate §291 add-back (20%); date-windowed QSBS per-issuer exclusion cap ($10M → $15M after July 4, 2025 under OBBBA) and gross-assets ceiling ($50M → $75M); the 5-year full-exclusion holding period; and the OBBBA tiered exclusion schedule (50/75/100% at 3/4/5 years) resolved by acquisition date. Additive; no removals.
1.33.0: Seam facts for downstream consumers. Washington estate graduated rate SCHEDULE (cited DOR Table W, resolved by date of death). New federal categories: recapture-rate (unrecaptured §1250 gain, 25%), charitable-agi-limit (appreciated LTCG property to public charity, 30%), charitable-carryforward (5 years), and estate-exemption-sunset (a counterfactual ~$7M pre-OBBBA figure for scenario modeling). Additive; no removals.
1.32.0: Tax-analyst review corrections. OBBBA federal standard deduction ($31,500 MFJ TY2025, $32,200 TY2026); new federal 2026 estate exemption ($15M); Washington estate top rate reverts to 20% for deaths on or after July 1, 2026. Engine fixes: removed a fabricated Vermont LTCG exclusion, dividend/interest now taxed in the state base, MN surcharge on net investment income (not wages), MA cross-class capital netting, CA surtax on taxable income, Philadelphia SIT clamped at $0, Rev. Proc. 2024-40 citation. Additive; no removals.
1.31.0: Encoded verified TY2026 top-rate cuts: Nebraska 4.55% (Neb. Rev. Stat. §77-2715.03) and West Virginia 4.58% (SB 392). Prior-year rates snapshotted to terminal facts; the two surveillance items resolved. Additive; no removals.
1.30.0: Added code to valueType for enumerated integer codes. qoz-conformity and migration-loss-conformity (values 0/1/2) now carry valueType code instead of none, so a consumer switching on none can always treat value as null. Additive; no removals.
1.6.0: Added U.S. territory jurisdictions (AS, GU, MP, PR, VI). Total catalog: 59 jurisdictions. JurisdictionLevel "territory" populated. No removals or type changes.
1.5.1: Spec corrections and hardening. ETag and conditional GET support for OpenAPI spec. Confidence and authority validation.
1.5.0: Added href to CitationDTO for direct link resolution. Added ?confidence= filter and /api/v1/health endpoint. Conditional GET support.
1.4.0: Added partial to valueType. Distinguishes conditional conformity from non-conformity.
1.3.0: Added qoz-conformity and qsbs-conformity fact categories.
1.2.0: Added valueType discriminant and optional derivation rules.