API Documentation

Getting Started

Nine endpoints, all POST, all JSON. Send your input, get a calculation back. Every response follows the same envelope:

{
  "success": true,
  "data": { ... },
  "input_echo": { ... },
  "meta": {
    "tax_year": 2026,
    "disclaimer": "..."
  }
}

input_echo mirrors back the values that were actually used, including defaults you didn't send. Handy for debugging.

Money values come back as strings, not floats — "2372.83" instead of 2372.83. No floating-point rounding surprises when dealing with tax math.

Errors

If something goes wrong, you get:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      {
        "field": "bruttolohn",
        "message": "Input should be greater than or equal to 0",
        "type": "greater_than_equal"
      }
    ]
  }
}

POST /v1/brutto-netto

Gross-to-net salary calculation for Germany.

Request Fields

Minimal Example

{"bruttolohn": 3500, "steuerklasse": 1}

Response Fields

Employee side: brutto_monat, brutto_jahr, netto_monat, netto_jahr, abzuege_gesamt_monat. Tax breakdown: lohnsteuer_monat, soli_monat, kirchensteuer_monat. Social security: kv_an_monat, pv_an_monat, rv_an_monat, av_an_monat, sv_gesamt_monat.

Employer side: ag_kv, ag_pv, ag_rv, ag_av, ag_umlage, ag_gesamt, ag_kosten_gesamt.

Rates applied: kv_satz, pv_satz, rv_satz, av_satz.

Scenarios: 5 what-if calculations at different gross salary levels (±500, ±1,000, +5,000 EUR).

POST /v1/grunderwerbsteuer

Property transfer tax and closing costs for real estate purchases in Germany.

Request Fields

Minimal Example

{"kaufpreis": 300000, "bundesland": "Bayern"}

Response Fields

kaufpreis, bundesland, steuersatz, grunderwerbsteuer (the tax itself). notarkosten, notar_prozent, grundbuchkosten, grundbuch_prozent (notary + land registry). maklerkosten, makler_prozent (0 if no broker). nebenkosten_gesamt, nebenkosten_prozent, kaufpreis_gesamt (totals).

bundeslaender_vergleich — array of all 16 states with their tax rate and what the transfer tax would be for your purchase price. Sorted by rate.

POST /v1/minijob

Determines employment type (Minijob up to 556 EUR, Midijob 556–2,000 EUR, regular) and calculates social security contributions.

Request Fields

Examples

{"bruttogehalt": 550}

{"bruttogehalt": 1200, "kinderlos_ueber_23": true, "bundesland": "Sachsen"}

Response Fields

status ("minijob", "midijob", or "volle_sv"). brutto, netto, sv_abzuege. kv_beitrag, pv_beitrag, rv_beitrag, av_beitrag (contribution breakdown). stunden_mindestlohn — hours per month at minimum wage (13.90 EUR/h).

vergleich_plus_100, vergleich_minus_100 — what happens to your net at ±100 EUR gross. hinweis — German explanation text about the employment status.

POST /v1/abfindung

Calculates tax on severance pay with and without the “fifth rule” (§34 EStG German income tax code).

Request Fields

Minimal Example

{"abfindung": 50000, "jahresbrutto": 60000}

Response Fields

fuenftelregel: est, soli, kirchensteuer, steuer_gesamt, netto, effektiv_prozent — tax with the fifth rule (reduced taxation for extraordinary income).

normal: Same fields — regular taxation without the fifth rule.

ersparnis — Tax savings from applying the fifth rule in EUR.

POST /v1/erbschaftsteuer

Inheritance and gift tax under ErbStG. Tax classes I–III, personal allowances, and comparison across all relationship types.

Request Fields

Minimal Example

{"wert": 500000, "verwandtschaft": "Kind"}

Response Fields

steuerklasse (I/II/III), freibetrag (allowance), versorgungsfreibetrag (care allowance), freibetrag_gesamt, steuerpflichtiger_erwerb (taxable amount). steuersatz, steuer, effektiv_prozent, netto, modus_label.

vergleich — array with tax calculation for all 12 relationship types.

POST /v1/weihnachtsgeld

Calculates net bonus payment (Christmas bonus, annual bonus). Compares standard taxation vs. sixth-rule (§39b EStG).

Request Fields

Minimal Example

{"monatslohn": 4000, "sonderzahlung": 4000}

Response Fields

brutto_sonderzahlung.

regulaer: lohnsteuer, soli, kirchensteuer, sv_abzuege, netto — standard withholding (employer method since 2025).

sechstelregel: Same fields — recoverable via tax return.

ersparnis, sechstel_anwendbar.

POST /v1/steuerklassen

Compares tax class combinations III/V vs. IV/IV for married couples.

Request Fields

Minimal Example

{"brutto_partner_1": 5000, "brutto_partner_2": 3000}

Response Fields

variante_3_5: partner_1 and partner_2 each with steuerklasse, brutto, netto, lohnsteuer, soli, kirchensteuer, sv_gesamt. Plus haushalt_netto.

variante_4_4: Same structure.

differenz_monat, differenz_jahr, empfehlung (recommendation text in German), warnungen (warnings).

POST /v1/einkommensteuer

Calculates income tax from taxable income (zvE) according to §32a EStG. Supports spousal splitting, solidarity surcharge, and church tax.

Request Fields

Minimal Example

{"zve": 50000}

Response Fields

einkommensteuer, solidaritaetszuschlag, kirchensteuer, steuer_gesamt — taxes in EUR. grenzsteuersatz — marginal tax rate on the next euro (percent). durchschnittssteuersatz — average tax rate (income tax / taxable income). belastungsquote — total tax burden (income tax + soli + church / taxable income).

tarifzone — zone (1–5), name, and satz of the current tax bracket.

grundfreibetrag — basic tax-free allowance in EUR (doubled for splitting).

POST /v1/sparplan

Savings plan and compound interest calculator with German capital gains tax (25% + 5.5% solidarity surcharge + optional church tax).

Request Fields

Minimal Example

{"monatliche_sparrate": 500, "laufzeit_jahre": 20}

Response Fields

endkapital_brutto, endkapital_netto — final capital before/after taxes. einzahlungen_gesamt — total contributions. ertraege_brutto, ertraege_netto — returns before/after taxes. steuer_gesamt — total capital gains tax paid. steuersatz_effektiv — effective tax rate incl. solidarity surcharge and church tax.

jahresverlauf — array with yearly development (einzahlungen_kumuliert, ertraege_kumuliert, steuer_kumuliert, kapital_brutto, kapital_netto, sparrate_monat).

Bundesland Values

Use exact German spelling (case-sensitive):