API Documentation

Getting Started

73 endpoints — 66 POST, 7 GET. You send input values, the API does the math, you get the result. Every response uses the same envelope:

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

input_echo shows you what the API actually used — including defaults you didn’t send. Saves you time when debugging.

Money values are strings, not floats — "2372.83" instead of 2372.83. No IEEE 754 rounding issues when you’re dealing with tax amounts.

Errors

When input doesn’t validate, the response looks like this:

{
  "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

Monthly gross salary in, full payslip breakdown out. Income tax, social security, employer costs — all itemized.

Request Fields

Minimal Example

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

Response Fields

Employee: brutto_monat/jahr, netto_monat/jahr, abzuege_gesamt_monat. Taxes: lohnsteuer_monat, soli_monat, kirchensteuer_monat. Social security: kv_an, pv_an, rv_an, av_an, sv_gesamt (all _monat).

Employer: ag_kv, ag_pv, ag_rv, ag_av, ag_umlage, ag_gesamt, ag_kosten_gesamt (total cost to employ).

Rates: kv_satz, pv_satz, rv_satz, av_satz — the actual percentages applied.

Scenarios: 5 what-if calculations — what changes at ±500, ±1,000 and +5,000 EUR gross.

POST /v1/brutto-netto

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

{
  "success": true,
  "data": {
    "netto_monat": "2351.83",
    "lohnsteuer_monat": "386.92",
    "soli_monat": "0.0",
    "sv_gesamt_monat": "761.25",
    "ag_kosten_gesamt": "4296.25"
  }
}

POST /v1/grunderwerbsteuer

Property transfer tax, notary fees, land registry, and broker commission — all closing costs at a glance.

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 — all 16 states side by side: tax rate and transfer tax for your purchase price. Sorted by rate.

POST /v1/grunderwerbsteuer

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

{
  "success": true,
  "data": {
    "grunderwerbsteuer": "10500.0",
    "notarkosten": "4500.0",
    "nebenkosten_gesamt": "16500.0",
    "kaufpreis_gesamt": "316500.0",
    "bundeslaender_vergleich": [...]
  }
}

POST /v1/minijob

Auto-detects Minijob (≤556 €), Midijob (556–2,000 €), or regular employment and calculates social security for both employee and employer.

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. Individual contributions: kv_beitrag, pv_beitrag, rv_beitrag, av_beitrag. stunden_mindestlohn — how many hours per month at 13.90 €/h minimum wage.

vergleich_plus_100, vergleich_minus_100 — net impact of ±100 € gross. hinweis — human-readable explanation of the employment status (in German).

POST /v1/minijob

{"bruttogehalt": 550}

{
  "success": true,
  "data": {
    "status": "minijob",
    "brutto": "550.0",
    "netto": "550.0",
    "sv_abzuege": "0.0",
    "stunden_mindestlohn": "39.6"
  }
}

POST /v1/abfindung

Severance tax with and without the “fifth rule” (§34 EStG). Shows the exact savings in euros.

Request Fields

Minimal Example

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

Response Fields

fuenftelregel: est, soli, kirchensteuer, steuer_gesamt, netto, effektiv_prozent — with reduced taxation for extraordinary income.

normal: Same fields — regular taxation, no fifth rule applied.

ersparnis — how much you save by applying the fifth rule, in EUR.

POST /v1/abfindung

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

{
  "success": true,
  "data": {
    "fuenftelregel": {
      "steuer_gesamt": "18279.36",
      "netto": "31720.64"
    },
    "normal": {
      "steuer_gesamt": "20930.27",
      "netto": "29069.73"
    },
    "ersparnis": "2650.91"
  }
}

POST /v1/erbschaftsteuer

Inheritance or gift — allowance, tax class, and tax liability under ErbStG. Compares all 12 relationship types in one response.

Request Fields

Minimal Example

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

Response Fields

steuerklasse (I/II/III), freibetrag, versorgungsfreibetrag, freibetrag_gesamt, steuerpflichtiger_erwerb. steuersatz, steuer, effektiv_prozent, netto, modus_label — the bottom line.

vergleich — same calculation for all 12 relationship types, so you can compare in one request.

POST /v1/erbschaftsteuer

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

{
  "success": true,
  "data": {
    "steuerklasse": "I",
    "freibetrag": "400000",
    "steuersatz": 11,
    "steuer": "11000.0",
    "netto": "489000.0",
    "vergleich": [...]
  }
}

POST /v1/weihnachtsgeld

How much of your bonus actually lands in your account? Compares standard withholding vs. sixth-rule (§39b EStG).

Request Fields

Minimal Example

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

Response Fields

brutto_sonderzahlung — the gross bonus amount.

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

sechstelregel: Same fields — the amount you can reclaim via your tax return.

ersparnis — the difference. sechstel_anwendbar — whether the sixth rule even applies.

POST /v1/weihnachtsgeld

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

{
  "success": true,
  "data": {
    "netto_regulaer": "2461.78",
    "netto_sechstel": "2478.78",
    "ersparnis": "17.0",
    "sechstel_anwendbar": true
  }
}

POST /v1/steuerklassen

III/V or IV/IV — which combo gives more take-home pay? Runs both variants for married couples.

Request Fields

Minimal Example

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

Response Fields

variante_3_5: Each partner gets steuerklasse, brutto, netto, lohnsteuer, soli, kirchensteuer, sv_gesamt. Plus haushalt_netto for the household.

variante_4_4: Same structure, different tax classes.

differenz_monat, differenz_jahr — the gap between both options. empfehlung — plain-text recommendation (German). warnungen — edge-case warnings.

POST /v1/steuerklassen

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

{
  "success": true,
  "data": {
    "differenz_monat": "361.17",
    "differenz_jahr": "4334.04",
    "empfehlung": "SK III/V bringt ...",
    "variante_3_5": {...},
    "variante_4_4": {...}
  }
}

POST /v1/einkommensteuer

Pure §32a income tax tariff. Taxable income in, tax + marginal rate + bracket info out. Splitting, solidarity surcharge, and church tax built in.

Request Fields

Minimal Example

{"zve": 50000}

Response Fields

einkommensteuer, solidaritaetszuschlag, kirchensteuer, steuer_gesamt — all in EUR. grenzsteuersatz — what the next euro costs you in tax. durchschnittssteuersatz — income tax divided by taxable income. belastungsquote — total burden (ESt + Soli + KiSt) as a percentage of income.

tarifzone — which of the 5 brackets you’re in, with name and rate range.

grundfreibetrag — the tax-free allowance (doubled when splitting applies).

POST /v1/einkommensteuer

{"zve": 50000}

{
  "success": true,
  "data": {
    "einkommensteuer": "10548.0",
    "grenzsteuersatz": "35.0",
    "durchschnittssteuersatz": "21.1",
    "tarifzone": {
      "zone": 3,
      "name": "Obere Progressionszone",
      "satz": "24–42 %"
    }
  }
}

POST /v1/sparplan

Compound interest with yearly tax settlement. 25% capital gains tax + solidarity surcharge, optionally church tax. Includes saver’s allowance and annual rate increases.

Request Fields

Minimal Example

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

Response Fields

endkapital_brutto, endkapital_netto — what you end up with, before and after tax. einzahlungen_gesamt — how much you put in total. ertraege_brutto, ertraege_netto — pure profit, before and after tax. steuer_gesamt — total capital gains tax deducted over the entire period. steuersatz_effektiv — effective rate including Soli and church tax.

jahresverlauf — year-by-year breakdown: cumulative contributions, returns, tax paid, gross/net capital, and monthly savings rate for that year.

POST /v1/sparplan

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

{
  "success": true,
  "data": {
    "einzahlungen_gesamt": "120000.0",
    "endkapital_brutto": "242719.78",
    "endkapital_netto": "215333.62",
    "steuer_gesamt": "27386.16",
    "jahresverlauf": [...]
  }
}

POST /v1/netto-brutto

Reverse calculation: enter your target net salary, get the required gross. Same tax and social security logic as brutto-netto.

Minimal example

{"nettolohn": 2500, "steuerklasse": 1}

Same optional fields as brutto-netto (bundesland, kirchensteuer, etc.)

POST /v1/lohnkosten-netto

How much net salary from a given employer cost budget? Reverse calc: budget in, gross and net out.

Minimal example

{"lohnkosten_ziel": 5000, "steuerklasse": 1}

POST /v1/arbeitgeber-kosten

Total employer cost breakdown: health, pension, unemployment, long-term care, U1/U2 levies, insolvency insurance.

Minimal example

{"brutto_monat": 4000}

POST /v1/pfaendung

Wage garnishment limits per §850c ZPO. Shows attachable and protected amounts, adjusted for dependents.

Minimal example

{"nettoeinkommen": 2500}

POST /v1/progressionsvorbehalt

Extra tax burden from wage replacement benefits (unemployment, parental, sick pay) per §32b EStG.

Minimal example

{"einkommen": 40000, "lohnersatzleistung": 10000}

POST /v1/gewerbesteuer

Trade tax for sole proprietors, partnerships and corporations. Includes exemption, 3.5% base rate, §35 credit and rate comparison across 7 assessment rates.

Minimal example

{"gewinn": 100000, "rechtsform": "kapitalgesellschaft", "hebesatz": 490}

Instead of hebesatz, you can pass ags (8-digit municipal code) or gemeinde (name search).

GET /v1/hebesaetze

Search 10,754 German municipalities by name. Returns trade tax assessment rate, AGS code and state.

Example

GET /v1/hebesaetze?q=M%C3%BCnchen&limit=5

GET /v1/hebesaetze/{ags}

Single lookup by 8-digit AGS, e.g. GET /v1/hebesaetze/09162000

POST /v1/koerperschaftsteuer

GmbH total tax burden: 15% corporate tax + solidarity surcharge + trade tax. Adds capital gains tax on distributions. Includes sole proprietor comparison.

Minimal example

{"gewinn": 100000, "hebesatz": 490}

Optional: ausschuettung_prozent (0–100, default 100), kirchenmitglied, bundesland

POST /v1/firmenwagen

Company car benefit: 1% rule for combustion, 0.5% for plug-in hybrids, 0.25% for pure EVs (up to €70k list price). Calculates the taxable benefit and net salary with vs. without the car.

Minimal example

{"listenpreis": 40000, "entfernung_km": 25, "antriebsart": "verbrenner", "bruttogehalt": 4000}

POST /v1/elterngeld

Parental allowance (Basiselterngeld + ElterngeldPlus). Replacement rate 65–67%, sibling bonus, multiple birth bonus, part-time option.

Minimal example

{"nettoeinkommen_monat": 2500}

POST /v1/alg1

Unemployment benefit (ALG I): assessment basis, flat-rate deductions, 60/67% benefit rate and entitlement period per §147 SGB III.

Minimal example

{"bruttogehalt_monat": 4000}

POST /v1/krankengeld

Sick pay: 70% of gross, capped at 90% of net. Deducts long-term care, pension and unemployment insurance (not health insurance). Shows income loss.

Minimal example

{"bruttogehalt_monat": 4000}

POST /v1/pendlerpauschale

German commuter allowance per §9 EStG. 0.38 EUR per one-way kilometer from km 1. The 4,500 EUR annual cap applies to public transport, bicycle and carpooling — not to driving your own car.

Minimal example

{"entfernung_km": 25, "grenzsteuersatz": 35}

POST /v1/schenkungsteuer

German gift tax (ErbStG). Tax classes I–III, personal allowances (20k–500k EUR), progressive rates (7–50%). Unlike inheritance, the care allowances per §17 do not apply to lifetime gifts.

Minimal example

{"wert": 450000, "verwandtschaft": "kind"}

POST /v1/grundsteuer

Property tax valid from 2025. Federal model for eleven states, plus five state-specific variants: Baden-Württemberg (land value), Bayern (area), Hamburg (residential zone), Hessen (area–factor), Niedersachsen (area–location). The required fields depend on the model — missing ones are surfaced in the error response.

Example (Bayern area model)

{"bundesland": "Bayern", "hebesatz_prozent": 535, "grundstuecksflaeche_m2": 500, "gebaeudeflaeche_m2": 140}

POST /v1/kurzarbeitergeld

Short-time work benefit per §§95–109 SGB III. 60% without children, 67% with. Applied to the flat-rate net difference per §106. Since 2026 a 21% SSC flat rate applies (was 20%).

Minimal example

{"brutto_regulaer": 3200, "ausfallstunden_prozent": 50, "hat_kinder": true}

POST /v1/buergergeld

German basic income support (SGB II). Standard needs, additional needs per §21, housing costs, and income offsetting with §11b allowances. The response includes a breakdown of how the deduction chain ran.

Minimal example

{"erwachsene": 2, "kinder_alter": [8, 12], "kaltmiete": 700, "heizkosten": 120, "nettoeinkommen": 1180}

POST /v1/bafoeg

German federal student aid (BAföG). Basic needs per §13, housing allowance, health insurance supplement per §13a, parental income with allowances per §25, own income per §23. Asset limits handled automatically.

Minimal example

{"ausbildungstyp": "hochschule", "bei_eltern": false, "alter": 22, "elterneinkommen_netto": 3200}

POST /v1/hebesaetze/bulk

Bulk lookup for up to 1,000 AGS codes per request. Unknown AGS are returned in nicht_gefunden instead of failing the whole request.

Minimal example

{"ags_liste": ["05315000", "09162000", "11000000"]}

POST /v1/szenario/jobwechsel

Job-change bundle: old vs. new net salary, severance with fifth-rule tax treatment, unemployment benefit I, and progression-reserve impact. Four calls reduced to one.

Example

{"altes_brutto_monat": 4500, "neues_brutto_monat": 5200, "abfindung": 25000, "arbeitslos_monate": 3}

POST /v1/szenario/familie

Family planning bundle: basic parental allowance, ElterngeldPlus, child benefit simulation, and a tax-class (III/V vs. IV/IV) recommendation. Useful before the baby arrives.

Example

{"nettoeinkommen_monat": 2500, "brutto_monat": 3800, "partner_brutto_monat": 5500, "geschwisterbonus": true}

POST /v1/szenario/immobilie

Property purchase bundle: transfer tax, annual property tax (computed using whichever state model applies), and closing costs (notary, land registry, optional broker).

Example

{"kaufpreis": 450000, "bundesland": "Bayern", "grundstuecksflaeche_m2": 500, "wohnflaeche_m2": 140, "hebesatz_grundsteuer_prozent": 535}

POST /v1/szenario/freelance-start

Freelance start bundle: total burden as a sole proprietor (income tax + solidarity + church + trade tax with §35 credit) vs. a GmbH (corporate tax + solidarity + trade + capital gains on distribution). Response names the net winner.

Example

{"gewinn_jahr": 120000, "hebesatz_gewerbesteuer": 475, "bundesland": "Nordrhein-Westfalen"}

POST /v1/verlustverrechnung

3-pot loss offsetting under §20 (6) EStG (stocks pot, other pot) and §23 EStG (crypto/private sales pot). Applies the saver allowance (1,000/2,000 EUR), the §23 exemption threshold (1,000 EUR), prior-year loss carry-overs and the pending Federal Constitutional Court ruling 2 BvL 3/21 on the stocks-pot restriction. Returns the estimated tax savings vs. a naive calculation without losses.

Request fields

Example

{"aktien_verluste_ytd": "3000", "sonstige_gewinne_ytd": "5000",
 "sonstige_verluste_ytd": "2000",
 "krypto_verluste_ytd": "1500", "krypto_gewinne_ytd": "800"}

Response fields (excerpt)

POST /v1/vorabpauschale

Advance lump-sum (Vorabpauschale) for accumulating ETF/funds under §18 InvStG for a full calendar year. Base yield = fund value start-of-year × base interest rate × 0.70, minus distributions, capped at the year's appreciation. Partial exemption under §20 InvStG by fund type. Base interest rate series 2018–2026 included (BMF circular each January). Special cases (negative base rate, loss year, distributions covering base yield) are flagged via keine_vap_grund.

Request fields

Example

{"fondswert_jahresanfang": "10000", "fondswert_jahresende": "11000",
 "fondstyp": "aktien_51", "jahr": 2026}

Response fields (excerpt)

POST /v1/kapitalertragsteuer

Calculates the withholding capital gains tax on an already CLEANED tax base (after saver allowance and loss offsetting): KapESt 25 % per §43a EStG, solidarity surcharge 5.5 % on KapESt (no phase-out for withholding, §4 SolzG), church tax 8 % (BY/BW) or 9 % (other states). When church tax applies, the §51a (2c) EStG closed-form formula KapESt = e / (4 + k) is used — many marketplace competitors ignore this and return the nominal 25 % instead of the correct ~24.51 % (BY/BW) or ~24.45 % (rest).

Request fields

Example

{"bemessungsgrundlage": "10000", "bundesland": "Bayern",
 "kirchensteuerpflichtig": true}

POST /v1/szenario/aktien-etf

Bundle endpoint: aggregates pre-tax (Vorabpauschale, §18 InvStG) + 3-pot loss offsetting (§20 (6) EStG + §23 EStG) + actual capital gains tax with state-specific church tax (§51a (2c) EStG closed-form formula) in a single call. Returns the real tax burden instead of the rough 26.375 % flat rate that most online calculators apply. Effective rate including church tax: 27.82 % (BY/BW, 8 % church) or 27.99 % (other states, 9 % church).

Request fields (all optional, default 0 or constant)

Example

{"aktien_gewinne_ytd": "5000", "aktien_verluste_ytd": "1500",
 "sonstige_gewinne_ytd": "2000",
 "bundesland": "Bayern", "kirchenmitglied": true}

Response fields (excerpt)

Bundesland Values

Must match exactly, including capitalization and hyphens: