api-ninjas-com Income Tax API

openapi: 3.2.0
info:
  title: Ninjas Income Tax 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
  description: The Income Tax API provides detailed information about current and historical income tax rates for different countries, including federal and state/provincial levels.
paths:
  /v2/incometax:
    get:
      summary: Retrieve income tax information
      description: Returns comprehensive income tax information including tax brackets and rates at both federal and state/provincial levels (where applicable).
      operationId: getIncomeTax
      parameters:
      - name: country
        in: query
        description: 2-letter country code (e.g., US, CA)
        required: true
        schema:
          type: string
      - name: year
        in: query
        description: The tax year for which to retrieve data
        required: true
        schema:
          type: integer
      - name: regions
        in: query
        description: Comma-separated list of regions to filter the response. For United States, specify 2-letter state codes (e.g., AL, CA, NY) or federal for federal tax information only. For Canada, specify 2-letter provincial codes (e.g., ON, BC, QC) or federal for federal tax information only. Multiple regions can be specified (e.g., federal,AL,CA,NY). When specified, filters the response to only include tax information for those regions. If unset, the response will include all regions (federal and all states/provinces).
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomeTaxOpenapi_IncomeTaxResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      tags:
      - Income Tax
components:
  schemas:
    IncomeTaxOpenapi_IncomeTaxResponse:
      type: object
      properties:
        country:
          type: string
          description: The country for which the tax rates are being retrieved.
        year:
          type: integer
          description: The tax year for which the tax rates are being retrieved.
        federal:
          type: object
          description: The federal tax rates for the given country and year.
          properties:
            single:
              type: object
              properties:
                brackets:
                  type: array
                  items:
                    $ref: '#/components/schemas/TaxBracket'
            married:
              type: object
              properties:
                brackets:
                  type: array
                  items:
                    $ref: '#/components/schemas/TaxBracket'
            married_separate:
              type: object
              properties:
                brackets:
                  type: array
                  items:
                    $ref: '#/components/schemas/TaxBracket'
            head_of_household:
              type: object
              properties:
                brackets:
                  type: array
                  items:
                    $ref: '#/components/schemas/TaxBracket'
        fica:
          type: object
          description: The FICA tax rates, including breakdown of social security and medicare percentages and social security cap, for the given country and year (US only).
          properties:
            fica_social_security_employee:
              type: number
              format: float
              description: Social Security tax rate for employees (percentage).
            fica_medicare_employee:
              type: number
              format: float
              description: Medicare tax rate for employees (percentage).
            fica_total_employee:
              type: number
              format: float
              description: Total FICA tax rate for employees (percentage).
            fica_social_security_self_employed:
              type: number
              format: float
              description: Social Security tax rate for self-employed (percentage).
            fica_medicare_self_employed:
              type: number
              format: float
              description: Medicare tax rate for self-employed (percentage).
            fica_total_self_employed:
              type: number
              format: float
              description: Total FICA tax rate for self-employed (percentage).
            cap:
              type: number
              description: Social Security wage base cap for the year.
        states:
          type: object
          description: The state tax rates for the given country and year (US only), keyed by 2-letter state code (e.g. CA).
          additionalProperties:
            type: object
            properties:
              single:
                type: object
                properties:
                  brackets:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxBracket'
              married:
                type: object
                properties:
                  brackets:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxBracket'
              married_separate:
                type: object
                properties:
                  brackets:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxBracket'
              head_of_household:
                type: object
                properties:
                  brackets:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxBracket'
              standard_deduction:
                type: object
                description: Standard deduction amounts for the state.
                properties:
                  single:
                    type: integer
                  couple:
                    type: integer
              personal_exemption:
                type: object
                description: Personal exemption amounts for the state.
                properties:
                  single:
                    type: integer
                  couple:
                    type: integer
                  dependent:
                    type: integer
        provinces:
          type: object
          description: The provincial tax rates for the given country and year (Canada only).
          additionalProperties:
            type: object
            properties:
              single:
                type: object
                properties:
                  brackets:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxBracket'
              married:
                type: object
                properties:
                  brackets:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxBracket'
              standard_deduction:
                type: object
                description: Standard deduction amounts for the province.
              personal_exemption:
                type: object
                description: Personal exemption amounts for the province.
    TaxBracket:
      type: object
      properties:
        rate:
          type: number
          format: float
          description: The tax rate for the bracket.
        min:
          type: number
          description: The minimum income for the bracket.
        max:
          type: number
          description: The maximum income for the bracket, or 'Infinity' for the highest bracket.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api