api-ninjas-com Income Tax Calculator API

openapi: 3.2.0
info:
  title: Ninjas Income Tax Calculator API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Income Tax Calculator
  description: The Income Tax Calculator API calculates detailed tax information based on income, location, and filing status using the latest tax rates for the United States (including state income tax and FICA) and Canada (including provincial income tax).
paths:
  /v1/incometaxcalculator:
    get:
      tags:
      - Income Tax Calculator
      summary: Calculates detailed tax information based on income, location, and filing status
      description: Calculates income tax for the United States or Canada from income, location, and filing status, including state or provincial tax. Requires `country`, `region`, `income`.
      operationId: calculateIncomeTax
      parameters:
      - name: country
        in: query
        description: 2-letter country code (e.g., US, CA)
        required: true
        schema:
          type: string
      - name: region
        in: query
        description: State/province code (e.g., CA, NY, ON)
        required: true
        schema:
          type: string
      - name: income
        in: query
        description: Annual income amount
        required: true
        schema:
          type: integer
      - name: filing_status
        in: query
        description: 'Tax filing status. Possible values: single, married (married filing jointly), married_separate (married filing separately), or head_of_household. Required when country is US.'
        required: false
        schema:
          type: string
          enum:
          - single
          - married
          - married_separate
          - head_of_household
      - name: deductions
        in: query
        description: Total tax deductions amount
        required: false
        schema:
          type: integer
          default: 0
      - name: credits
        in: query
        description: Total tax credits amount
        required: false
        schema:
          type: integer
          default: 0
      - name: self_employed
        in: query
        description: Set to true for self-employed tax calculations (US only)
        required: false
        schema:
          type: boolean
          default: false
      - name: tax_year
        in: query
        description: Tax year in YYYY format (e.g., 2024). If not specified, the latest year will be used.
        required: false
        schema:
          type: string
          pattern: ^\d{4}$
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomeTaxResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
  /v1/paycheckwithholding:
    get:
      tags:
      - Income Tax Calculator
      summary: Calculates per-paycheck federal, state and FICA withholding from W-4 inputs
      description: Premium only. Returns per-paycheck federal withholding, FICA (Social Security, Medicare, Additional Medicare), and optional state withholding given gross pay and W-4 inputs. Supports both the 2020-or-later and pre-2020 W-4 forms. Requires `gross_pay`, `pay_period`, `filing_status`.
      operationId: calculatePaycheckWithholding
      parameters:
      - name: gross_pay
        in: query
        description: Gross pay for the period (in dollars).
        required: true
        schema:
          type: number
      - name: pay_period
        in: query
        description: 'Pay period. One of: weekly, biweekly, semimonthly, monthly, quarterly, semiannually, annually, daily.'
        required: true
        schema:
          type: string
          enum:
          - weekly
          - biweekly
          - semimonthly
          - monthly
          - quarterly
          - semiannually
          - annually
          - daily
      - name: filing_status
        in: query
        description: 'Tax filing status. Possible values: single, married (married filing jointly), married_separate, or head_of_household.'
        required: true
        schema:
          type: string
          enum:
          - single
          - married
          - married_separate
          - head_of_household
      - name: state
        in: query
        description: 2-letter US state code. Omit for federal-only calculation.
        required: false
        schema:
          type: string
      - name: tax_year
        in: query
        description: Tax year (YYYY). Defaults to the current year.
        required: false
        schema:
          type: integer
      - name: w4_version
        in: query
        description: 'Selects which W-4 worksheet to use: 2020_or_later (default) or pre_2020.'
        required: false
        schema:
          type: string
          enum:
          - 2020_or_later
          - pre_2020
          default: 2020_or_later
      - name: multiple_jobs
        in: query
        description: W-4 Step 2(c) "multiple jobs" checkbox (2020+ W-4 only).
        required: false
        schema:
          type: boolean
          default: false
      - name: dependents_amount
        in: query
        description: W-4 Step 3 total annual credit for dependents (2020+ W-4).
        required: false
        schema:
          type: number
      - name: other_income
        in: query
        description: W-4 Step 4(a) annual other income (2020+ W-4).
        required: false
        schema:
          type: number
      - name: deductions
        in: query
        description: W-4 Step 4(b) annual deductions over the standard deduction (2020+ W-4).
        required: false
        schema:
          type: number
      - name: extra_withholding
        in: query
        description: W-4 Step 4(c) extra per-period withholding (added directly to federal withholding).
        required: false
        schema:
          type: number
      - name: allowances
        in: query
        description: Pre-2020 W-4 only. Number of allowances claimed on line 5 of the 2019-or-earlier W-4.
        required: false
        schema:
          type: integer
      - name: pretax_deductions
        in: query
        description: Pre-tax deductions for this paycheck (401(k), HSA, cafeteria plans). Reduces taxable wages.
        required: false
        schema:
          type: number
      - name: ytd_gross
        in: query
        description: 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.
        required: false
        schema:
          type: number
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaycheckWithholdingResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
components:
  schemas:
    IncomeTaxResponse:
      type: object
      properties:
        country:
          type: string
          example: US
        region:
          type: string
          example: CA
        income:
          type: number
          example: 100000
        taxable_income:
          type: number
          example: 100000
        deductions:
          type: number
          example: 0
        credits:
          type: number
          example: 0
        tax_year:
          type: string
          example: '2026'
        federal_effective_rate:
          type: number
          format: float
          example: 0.17053
        federal_taxes_owed:
          type: number
          example: 17053
        fica_social_security:
          type: number
          example: 6200
        fica_social_security_rate:
          type: number
          format: float
          example: 0.062
        fica_social_security_cap:
          type: integer
          example: 184500
        fica_medicare:
          type: number
          example: 1450
        fica_medicare_rate:
          type: number
          format: float
          example: 0.0145
        fica_total:
          type: number
          example: 7650
        region_effective_rate:
          type: number
          format: float
          example: 0.05952849999999999
        region_taxes_owed:
          type: number
          example: 5952.849999999999
        total_taxes_owed:
          type: number
          example: 30655.85
        income_after_tax:
          type: number
          example: 69344.15
        total_effective_tax_rate:
          type: number
          format: float
          example: 0.3065585
    PaycheckWithholdingResponse:
      type: object
      properties:
        gross_pay:
          type: number
          description: Gross pay for the period (echoed back).
          example: 5000
        pay_period:
          type: string
          description: Pay period (echoed back).
          example: biweekly
        tax_year:
          type: integer
          description: Tax year used for the calculation.
          example: 2026
        filing_status:
          type: string
          description: Filing status used.
          example: single
        w4_version:
          type: string
          description: W-4 worksheet version applied.
          example: 2020_or_later
        pretax_deductions:
          type: number
          description: Pre-tax deductions used in the calculation.
          example: 0
        taxable_wages:
          type: number
          description: Gross pay minus pre-tax deductions.
          example: 5000
        federal_withholding:
          type: number
          description: Federal income tax withheld for this paycheck (including extra withholding).
          example: 766.69
        fica:
          type: object
          description: FICA taxes for this paycheck.
          properties:
            social_security:
              type: number
              description: Social Security tax for this paycheck (6.2% up to the annual wage base).
              example: 310
            medicare:
              type: number
              description: Medicare tax for this paycheck (1.45%).
              example: 72.5
            additional_medicare:
              type: number
              description: Additional Medicare tax for this paycheck (0.9% on YTD wages above $200,000).
              example: 0
            total:
              type: number
              description: Sum of all FICA components.
              example: 382.5
        state:
          type: string
          description: 2-letter state code (echoed back) when state was supplied.
          example: CA
        state_withholding:
          type: number
          description: State income tax withheld for this paycheck. 0 for no-tax states.
          example: 338.38
        total_withholding:
          type: number
          description: Federal + FICA + state withholding combined.
          example: 1487.57
        take_home_pay:
          type: number
          description: Taxable wages minus total withholding.
          example: 3512.43
        annualized:
          type: object
          description: Annualized projections, extrapolating this paycheck across the year.
          properties:
            gross:
              type: number
              example: 130000
            federal_withholding:
              type: number
              example: 19933.94
            take_home:
              type: number
              example: 91323.18
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api