NewConnect Claude, Gemini, ChatGPT, and other AI agents to API Ninjas via our MCP server →

Income Tax Calculator API

The Income Tax Calculator API provides detailed tax calculations for the United States and Canada. Annual tax calculation supports federal, state/provincial, and FICA. Per-paycheck calculation uses IRS Publication 15-T W-4 worksheets and supports both the 2020-or-later and pre-2020 W-4 forms.

Available endpoints:

Only interested in getting current and historical income tax rates? Check out our Income Tax API.

(4.5)

From 2,366 users

1,000+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average
P50
P75
P90
P95
314ms348ms392ms580ms1081ms

Didn't find what you were looking for? Suggest an improvement

/v1/incometaxcalculator GET

https://api.api-ninjas.com/v1/incometaxcalculator

Returns comprehensive annual tax calculations including federal, state/provincial, and FICA taxes where applicable.

Parameters

  • country  required

    2-letter country code (e.g., US, CA)

  • region  required

    State/province code (e.g., CA, NY, ON)

  • income  required

    Annual income amount

  • tax_year  optional

    Tax year in YYYY format (e.g., 2026). If not specified, the latest year will be used.

  • filing_status  required for US

    Tax filing status. Possible values: single, married (married filing jointly), married_separate (married filing separately), or head_of_household

  • deductions  optional

    Total tax deductions amount

  • credits  optional

    Total tax credits amount

  • self_employed  optional

    Set to true for self-employed tax calculations (US only)

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON object with the following fields or an error if the request is unsuccessful.

  • country

    The country code used in the calculation.

  • region

    The state/province code used in the calculation.

  • income

    The annual income amount.

  • taxable_income

    Income after deductions.

  • deductions

    Total deductions applied.

  • credits

    Total tax credits applied.

  • federal_effective_rate

    Effective federal tax rate as a decimal.

  • federal_taxes_owed

    Total federal taxes owed.

  • fica_social_security premium only

    Social Security tax amount - US only.

  • fica_social_security_rate premium only

    Social Security tax rate as a decimal - US only.

  • fica_social_security_cap premium only

    Social Security wage base cap - US only.

  • fica_medicare premium only

    Medicare tax amount - US only.

  • fica_medicare_rate premium only

    Medicare tax rate as a decimal - US only.

  • fica_total premium only

    Total FICA taxes (Social Security + Medicare taxes) - US only.

  • region_effective_rate premium only

    Effective state/provincial tax rate as a decimal.

  • region_taxes_owed premium only

    Total state/provincial taxes owed.

  • total_taxes_owed premium only

    Total taxes owed (federal + state/provincial + FICA).

  • income_after_tax premium only

    Income remaining after all taxes.

  • total_effective_tax_rate premium only

    Overall effective tax rate as a decimal.

Sample Request Live Demo!

country
region
income
tax_year
filing_status

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

https://api.api-ninjas.com/v1/incometaxcalculator?country=US&region=CA&income=100000&filing_status=single&tax_year=2026

Headers

X-Api-KeyLog in or sign up to get your API Key

Sample Response

JSON
{
    country:"US",
    region:"CA",
    income:100000,
    taxable_income:100000,
    deductions:0,
    credits:0,
    tax_year:"2026",
    federal_effective_rate:0.1671188,
    federal_taxes_owed:16711.88,
    fica_social_security:6200,
    fica_social_security_rate:0.062,
    fica_social_security_cap:184500,
    fica_medicare:1450,
    fica_medicare_rate:0.0145,
    fica_total:7650,
    region_effective_rate:0.05842107,
    region_taxes_owed:5842.107,
    total_taxes_owed:30203.987,
    income_after_tax:69796.013,
    total_effective_tax_rate:0.30203987
}

Code Examples

1 2 curl -X GET "https://api.api-ninjas.com/v1/incometaxcalculator?country=US&region=CA&income=100000&filing_status=single&tax_year=2026" \ -H "X-Api-Key: YOUR_API_KEY"

If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.

/v1/paycheckwithholding GET premium only

https://api.api-ninjas.com/v1/paycheckwithholding

Returns per-paycheck federal withholding, FICA (Social Security, Medicare, Additional Medicare), and optional state withholding given gross pay and W-4 inputs. Federal withholding uses IRS Publication 15-T percentage method tables for both the 2020-or-later and pre-2020 W-4 forms.

Parameters

  • gross_pay  required

    Gross pay for the period (in dollars).

  • pay_period  required

    One of: weekly, biweekly, semimonthly, monthly, quarterly, semiannually, annually, daily.

  • filing_status  required

    One of: single, married (married filing jointly), married_separate, head_of_household.

  • state  optional

    2-letter US state code. Omit for federal-only calculation.

  • tax_year  optional

    Tax year (YYYY). Defaults to the current year. Currently supported: 2026.

  • w4_version  optional

    2020_or_later (default) or pre_2020. Selects which W-4 worksheet to use.

  • multiple_jobs  optional

    W-4 Step 2(c) "multiple jobs" checkbox (2020+ W-4 only). true or false. Default false.

  • dependents_amount  optional

    W-4 Step 3 total annual credit for dependents (2020+ W-4).

  • other_income  optional

    W-4 Step 4(a) annual other income (2020+ W-4).

  • deductions  optional

    W-4 Step 4(b) annual deductions over the standard deduction (2020+ W-4).

  • extra_withholding  optional

    W-4 Step 4(c) extra per-period withholding (added directly to federal withholding).

  • allowances  optional

    Pre-2020 W-4 only. Number of allowances claimed on line 5 of the 2019-or-earlier W-4.

  • pretax_deductions  optional

    Pre-tax deductions for this paycheck (401(k), HSA, cafeteria plans). Reduces taxable wages.

  • ytd_gross  optional

    Year-to-date gross wages before this paycheck. Used to apply the Social Security wage base cap and the 0.9% Additional Medicare tax above $200,000 YTD.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON object with the following fields or an error if the request is unsuccessful.

  • gross_pay

    Gross pay for the period (echoed back).

  • pay_period

    Pay period (echoed back).

  • tax_year

    Tax year used for the calculation.

  • filing_status

    Filing status used.

  • w4_version

    W-4 worksheet version applied.

  • pretax_deductions

    Pre-tax deductions used in the calculation.

  • taxable_wages

    Gross pay minus pre-tax deductions.

  • federal_withholding

    Federal income tax withheld for this paycheck (including extra withholding).

  • fica.social_security

    Social Security tax for this paycheck (6.2% up to the annual wage base).

  • fica.medicare

    Medicare tax for this paycheck (1.45%).

  • fica.additional_medicare

    Additional Medicare tax for this paycheck (0.9% on YTD wages above $200,000).

  • fica.total

    Sum of all FICA components.

  • state

    2-letter state code (echoed back) when state was supplied.

  • state_withholding

    State income tax withheld for this paycheck. 0 for no-tax states.

  • total_withholding

    Federal + FICA + state withholding combined.

  • take_home_pay

    Taxable wages minus total withholding.

  • annualized

    Annualized projections: gross, federal withholding, and take-home — extrapolating this paycheck across the year.

Sample Request Live Demo!

gross_pay
pay_period
filing_status
state
tax_year

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

https://api.api-ninjas.com/v1/paycheckwithholding?gross_pay=5000&pay_period=biweekly&filing_status=single&tax_year=2026

Headers

X-Api-KeyLog in or sign up to get your API Key

Sample Response

JSON
{
    gross_pay:5000,
    pay_period:"biweekly",
    tax_year:2026,
    filing_status:"single",
    w4_version:"2020_or_later",
    pretax_deductions:0,
    taxable_wages:5000,
    federal_withholding:925.46,
    fica:{
      social_security:310,
      medicare:72.5,
      additional_medicare:0,
      total:382.5
    },
    total_withholding:1307.96,
    take_home_pay:3692.04,
    annualized:{
      gross:130000,
      federal_withholding:24061.96,
      take_home:96002.96
    }
}

Code Examples

1 2 curl -X GET "https://api.api-ninjas.com/v1/paycheckwithholding?gross_pay=5000&pay_period=biweekly&filing_status=single&tax_year=2026" \ -H "X-Api-Key: YOUR_API_KEY"

Frequently Asked Questions

  • Yes, but you must have a premium subscription. Commercial use of the Income Tax Calculator API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.
  • Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.
  • Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.
  • The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.
  • The API powers tax estimators, salary and offer-comparison tools, and payroll previews for the US and Canada: the /v1/incometaxcalculator endpoint computes annual federal, state/provincial, and FICA liability from income, region, and filing_status, while the /v1/paycheckwithholding endpoint models per-paycheck take-home pay. If you only need raw current and historical bracket rates instead, see the Income Tax API.
  • Call the /v1/incometaxcalculator endpoint with the required country (e.g. US or CA), region (state/province code like CA, NY, or ON), and income parameters, plus filing_status (single, married, married_separate, or head_of_household) which is required for the US. You can refine the result with optional deductions, credits, tax_year, and self_employed parameters, or browse our other finance tools in the API catalog.
  • The /v1/paycheckwithholding endpoint computes federal withholding using IRS Publication 15-T percentage method tables (supporting both the 2020_or_later and pre_2020 W-4 forms via w4_version) and returns federal_withholding, a fica object (Social Security, Medicare, and additional Medicare), optional state_withholding, total_withholding, take_home_pay, and an annualized projection. This endpoint is premium only and accepts W-4 inputs such as dependents_amount, other_income, extra_withholding, and ytd_gross.
  • On the annual /v1/incometaxcalculator endpoint, fields like federal_taxes_owed and taxable_income are available on all plans, while the FICA breakdown (fica_social_security, fica_medicare, fica_total), region_taxes_owed, total_taxes_owed, income_after_tax, and total_effective_tax_rate are premium only. The entire /v1/paycheckwithholding endpoint also requires a premium subscription.