AnyTax Estimator API

openapi: 3.2.0
info:
  title: Anytax Public API v1 Estimator API
  description: '## Machine-readable resources


    | Resource | URL | Use for |

    |---|---|---|

    | OpenAPI JSON | `/v1-json` | Import into Cursor / Copilot / Claude Projects as a spec file |

    | OpenAPI YAML | `/v1-yaml` | Same spec in YAML for tools that prefer `.yaml` |

    | LLM guide | `/llms.txt` | AI agents that fetch `llms.txt` for narrative docs |


    ---


    # AnyTax Partner Integration Guide


    This guide is written for **integration teams** embedding AnyTax into an existing product. It explains how to authenticate your end users, call our public REST APIs from your backend, and follow security expectations for a production SaaS integration. You will find authentication flows, endpoint reference, sequence diagrams, and reference implementations in **TypeScript**, **Java**, and **Python**. ---


    ### Table of contents


    1. Overview

    2. Prerequisites

    3. Authentication Endpoints

    - Register a User

    - Login a User

    4. Protected API Endpoints

    - Get User Profile

    - List Scenarios

    - List Filings

    - Create a Filing

    - Prefill a Filing

    - Refresh Token

    5. Partner-Initiated SSO (Silent Login)

    - SSO quickstart (step by step)

    - Mint an SSO code

    - Exchange the code

    6. Integration Architecture

    - Option A — Server Proxy

    - Option B — Client Direct

    7. Sequence Diagrams

    8. Complete Code Examples

    - TypeScript / Node.js

    - Java

    - Python

    9. Error Handling

    10. Security Best Practices

    11. Import from ELSTER


    ---


    ## Overview


    AnyTax is a multi-tenant platform. As a **partner**, you integrate your application so your customers can complete German tax filings without leaving your product experience. At a high level you will:


    - **Provision** end-user accounts under your partner tenant using server-to-server calls (no OTP in this flow). - **Authenticate** returning users and obtain JWT access tokens for API access. - **Orchestrate** tax scenarios, filings, answers, and related flows through the same public APIs your users would use in our first-party experience. End users are scoped by **`(email + partner)`**: the same email may exist for different partners without collision. ### How the integration works


    1. During onboarding, AnyTax issues a **partner slug** and **client secret** for your environment. 2. Your **backend** calls register or login with those credentials plus the end user’s email. 3. AnyTax returns a **JWT access token** (RS256, short-lived; see Refresh Token). 4. Your services use that token in the `Authorization` header for all subsequent calls on behalf of that user. ---


    ## Prerequisites


    | Item | Description |

    | ----------------- | ------------------------------------------------------------------------------------ |

    | **Partner slug** | Stable identifier for your partner tenant (for example `my-partner`). |

    | **Client secret** | Rotatable credential issued with your slug. **Use only on trusted servers.** |

    | **Base URL** | Environment-specific API origin (for example `https://api.anytax.io` in production). |


    > **Security:** Treat the client secret like any other production API key. Register and login requests must originate from **your backend**—never from a browser bundle, mobile app, or public repository. ---


    ## Authentication Endpoints


    ### 1. Register a User


    Creates a new user under your partner and returns a JWT token.'
  version: 1.18.12
  contact: {}
servers: []
tags:
- name: Estimator
paths:
  /estimator:
    get:
      operationId: EstimatorController_getEstimate
      parameters:
      - name: x-api-key
        required: false
        in: header
        description: API key for authentication
        schema:
          type: string
      - name: income
        required: true
        in: query
        description: What was your gross income from employment?
        schema:
          example: 50000
          type: number
      - name: distanceToWork
        required: true
        in: query
        description: How far was your one-way distance to work?
        schema:
          example: 10
          type: number
      - name: workFromHomeDays
        required: true
        in: query
        description: How many days did you work from home?
        schema:
          example: 50
          type: number
      - name: workExpenses
        required: false
        in: query
        description: Other work-related expenses (Laptop etc)?
        schema:
          example: 1000
          type: number
      - name: specialExpenses
        required: false
        in: query
        description: Special expenses (like Childcare, school fees, own education costs)
        schema:
          example: 0
          type: number
      - name: taxWithheld
        required: false
        in: query
        description: 'Would you like to enter your actual income tax withheld for a more detailed result? '
        schema:
          type: number
      - name: married
        required: true
        in: query
        description: Were you married during the tax year and would file jointly?
        schema:
          example: false
          type: boolean
      - name: children
        required: true
        in: query
        description: How many children did you have?
        schema:
          example: 2
          type: number
      - name: householdServices
        required: false
        in: query
        description: Household-related services and craftsmen's services (labour costs only)
        schema:
          example: 400
          type: number
      - name: spouseIncome
        required: false
        in: query
        description: Spouse’s gross income
        schema:
          example: 30000
          type: number
      - name: spouseDistanceToWork
        required: false
        in: query
        description: How far for your spouse was your one-way distance to work?
        schema:
          example: 15
          type: number
      - name: spouseWorkFromHomeDays
        required: false
        in: query
        description: How many days did your spouse work from home?
        schema:
          example: 100
          type: number
      - name: spouseWorkExpenses
        required: false
        in: query
        description: Spouse other work-related expenses (Laptop etc)?
        schema:
          example: 0
          type: number
      - name: spouseSpecialExpenses
        required: false
        in: query
        description: Spouse special expenses (like Childcare, school fees, own education costs)
        schema:
          example: 500
          type: number
      - name: spouseHouseholdServices
        required: false
        in: query
        description: Spouse household-related services and craftsmen's services (labour costs only)
        schema:
          example: 200
          type: number
      responses:
        '200':
          description: Calculated tax details
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/ResponseEstimatorDto'
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
        '400':
          description: Invalid input
        '401':
          description: Unauthorized - Invalid API key
      summary: Estimate the tax refund or liability
      tags:
      - Estimator
      security:
      - bearer: []
      description: '**Responses**


        | Status | Meaning |

        | ------ | ------- |

        | `200` | Calculated tax details |

        | `400` | Invalid input |

        | `401` | Unauthorized - Invalid API key |'
      x-anytax-docs-enriched: true
  /estimator/all:
    get:
      operationId: EstimatorController_getAllFilings
      parameters:
      - name: page
        required: false
        in: query
        description: Page number
        schema:
          example: 1
          type: number
      - name: limit
        required: false
        in: query
        description: Number of items per page
        schema:
          example: 100
          type: number
      - name: filter
        required: false
        in: query
        description: filter out test values?
        schema:
          example: 'true'
          type: string
      responses:
        '200':
          description: Ok
        '404':
          description: Not ok
      tags:
      - Estimator
      security:
      - bearer: []
      description: '**Responses**


        | Status | Meaning |

        | ------ | ------- |

        | `200` | Ok |

        | `404` | Not ok |'
      x-anytax-docs-enriched: true
      summary: Estimator controller get all filings
      x-summary-source: derived
components:
  schemas:
    ResponseEstimatorDto:
      type: object
      properties:
        estimatedTax:
          type: number
          description: Estimated tax refund or liability
          example: 3000
        taxableIncome:
          type: number
          description: Calculated taxable income
          example: 45000
        taxBeforeWithholding:
          type: number
          description: Income tax before withholding
          example: 5000
        finalTaxDue:
          type: number
          description: Final tax due
          example: 2000
      required:
      - estimatedTax
      - taxableIncome
      - taxBeforeWithholding
      - finalTaxDue
    ApiMeta:
      type: object
      required:
      - timestamp
      properties:
        timestamp:
          type: string
          format: date-time
          example: '2025-01-19T10:30:00.000Z'
        responseTime:
          type: number
          example: 42
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    api-key:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for programmatic authentication
x-tagGroups:
- name: Partner platform
  tags:
  - Partner platform
  - Filing Eligibility Check
- name: User Management
  tags:
  - Auth API
  - User API
- name: Tax Services
  tags:
  - Filing API
  - Scenario API
  - Question API
  - Answer API
  - Navigation API
  - Wage Tax API
  - Tax Saving Tip API
  - ELSTER Import API