Free Developer Tool

Free state residency rules and tax delta API

Two unauthenticated, open-CORS endpoints built from the same 56 researched jurisdiction dossiers and 2026 tax bracket data that power the ResidencyIQ site: state income tax deltas and statutory residency rules, both with cited sources.

No API key, no signup. Free to use with an attribution link back to residencyiq.app.

Access and limits

Requests: 60 per minute, per IP address

Auth: None required

CORS: Open (Access-Control-Allow-Origin: *), GET only

Over limit: 429 response with a Retry-After header (seconds)

Attribution license

Free to use, including in published or commercial work, on the condition that you keep a visible link back to residencyiq.app anywhere you publish data pulled from this API. Every response includes an attribution object stating this.

This is general information, not tax or legal advice. Every figure and rule quote traces to a cited source in the response; verify against the primary source before relying on it for a filing or client-facing position.

Endpoint

GET /api/public/v1/tax-delta

Estimated annual state income tax for two jurisdictions at a given income and filing status, the delta between them, both jurisdictions' statutory residency day-count threshold, and source citations. The same math and 2026 bracket data behind the calculator.

Param	Required	Description
from	Yes	Origin jurisdiction slug, e.g. "california". See the full list below.
to	Yes	Destination jurisdiction slug, e.g. "texas".
income	Yes	Annual gross income, a non-negative number, e.g. 250000.
filing	No	"single" or "joint". Defaults to "single".

Example request

curl "https://residencyiq.app/api/public/v1/tax-delta?from=california&to=texas&income=250000&filing=single"

Example response

{
  "data": {
    "from": {
      "state": "california",
      "stateName": "California",
      "abbr": "CA",
      "filingStatus": "single",
      "annualIncome": 250000,
      "estimatedAnnualTax": 19173.42,
      "effectiveRate": 0.0767,
      "marginalRate": 0.093,
      "computable": true,
      "summary": "California taxes this income at a top marginal rate of 9.3% under its bracket schedule.",
      "residencyThreshold": {
        "dayCountThreshold": null,
        "statutoryResidencyTest": "California does not use a bright-line day count as its primary test..."
      }
    },
    "to": {
      "state": "texas",
      "stateName": "Texas",
      "abbr": "TX",
      "filingStatus": "single",
      "annualIncome": 250000,
      "estimatedAnnualTax": 0,
      "effectiveRate": 0,
      "marginalRate": 0,
      "computable": true,
      "summary": "Texas has no state individual income tax on wages, salaries, interest, dividends, or capital gains.",
      "residencyThreshold": {
        "dayCountThreshold": null,
        "statutoryResidencyTest": "Texas has no state individual income tax and no statutory residency day-count test tied to it..."
      }
    },
    "delta": {
      "computable": true,
      "annual": 19173.42,
      "monthly": 1597.79,
      "direction": "savings",
      "summary": "Moving from California to Texas would save an estimated $19,173 per year in state income tax at this income."
    }
  },
  "taxYear": 2026,
  "citations": [
    { "title": "2026 State Individual Income Tax Rates and Brackets", "url": "https://taxfoundation.org/...", "publisher": "Tax Foundation", "accessed": "2026-08-05" }
  ],
  "attribution": {
    "required": true,
    "link": "https://residencyiq.app",
    "license": "Free with attribution link"
  },
  "disclaimer": "General information, not tax or legal advice. Verify against the cited primary sources before relying on this for a filing or residency decision."
}

effectiveRate and marginalRate are decimal fractions (0.093 = 9.3%), shown rounded above for readability. Territories return computable: false with an honest explanatory summary instead of a fabricated rate.

Endpoint

GET /api/public/v1/residency-rules/:state

One jurisdiction's full statutory residency test, domicile test, day-count threshold, any-part-of-day rule, presumptions, and safe harbors, with source citations. :state is a jurisdiction slug, e.g. california, washington-dc, or puerto-rico. See the full jurisdiction list for all 56 slugs.

Example request

curl "https://residencyiq.app/api/public/v1/residency-rules/california"

Example response

{
  "data": {
    "slug": "california",
    "name": "California",
    "abbr": "CA",
    "kind": "state",
    "residencyTests": {
      "statutoryResidencyTest": "California does not use a bright-line day count as its primary test. Under Revenue and Taxation Code Section 17014 and FTB Publication 1031, a resident is anyone present in California for other than a temporary or transitory purpose...",
      "domicileTest": "FTB Publication 1031 defines domicile as the place you have your true, fixed, permanent home...",
      "dayCountThreshold": null,
      "anyPartOfDayRule": "Yes. FTB counts any presence in California, even a few hours, as a full day...",
      "presumptions": "Revenue and Taxation Code Section 17016: an individual present in California for more than nine months...",
      "safeHarbors": [
        { "name": "546-day overseas/out-of-state employment contract safe harbor", "description": "...", "citation": "R&TC Section 17014(d)" }
      ]
    },
    "safeHarbors": [ /* same array as residencyTests.safeHarbors, repeated at the top level for convenience */ ],
    "exitStickiness": 5,
    "auditAggressiveness": 5
  },
  "citations": [
    { "title": "FTB Publication 1031, Guidelines for Determining Resident Status (2024)", "url": "https://www.ftb.ca.gov/forms/2024/2024-1031-publication.pdf", "publisher": "California Franchise Tax Board", "accessed": "2026-08-05" }
  ],
  "attribution": {
    "required": true,
    "link": "https://residencyiq.app",
    "license": "Free with attribution link"
  },
  "disclaimer": "General information, not tax or legal advice. Verify against the cited primary sources before relying on this for a filing or residency decision."
}

Errors

Status	Meaning
400	Missing or invalid query params (unknown slug, missing income, bad filing value).
404	residency-rules/:state only: the slug is not one of the 56 supported jurisdictions.
429	Rate limit exceeded. Response includes limit and retryAfterSeconds; the Retry-After header is set in seconds.
503	tax-delta only: tax table data is not yet published for one of the requested jurisdictions.

Also embeddable, no API required

Prefer a ready-made widget instead of calling the API yourself? Both underlying tools have a free iframe embed with the same attribution terms.

See embeddable tools

Start your record

Build your Public API mobility map.

Start with a free map, document your center of life, then upgrade when you need evidence, advisor collaboration, and audit-ready reporting.

Create Free Mobility Map