tools

Calculate detailed payroll and net salary for one country and person. Use this for tax class, region, health insurance, pension, deductions, or other country-specific inputs. For the same gross salary across two or more countries, use taxcompare. Use semantic fields where available; legacy fields remain REST compatibility inputs. Monetary fields in the legacy request are minor units and period-specific.

post/api/berechne

Request

  • Base URL: https://localhost:10000
  • URL: https://localhost:10000/api/berechne
  • Auth: one of:
    • API key in header x-public-api-key
    • HTTP bearer

Request body

country'DE' | 'AT' | 'US' | 'CH' | 'CA' | 'AU' | 'UK' | 'IE'

Preferred high-level country code for MCP calls. For German payroll use DE. The adapter maps this to legacy Land.

tax_yearinteger

Preferred high-level tax year for MCP calls. The adapter maps this to legacy Stjahr.

ageinteger

Age in the selected tax year. If omitted, the calculation reports the standard age-35 assumption instead of silently hiding the default.

employee_type'standard_statutory_employee' | 'private_health_insurance' | 'pension_exempt' | 'pension_exempt_private_health'

Preferred high-level German employee type. Use standard_statutory_employee for the common statutory pension, unemployment, health, and care insurance case.

payroll_preset'DE_STANDARD_EMPLOYEE_STATUTORY' | 'DE_PRIVATE_HEALTH_INSURANCE' | 'DE_PENSION_EXEMPT' | 'DE_PENSION_EXEMPT_PRIVATE_HEALTH'

Preferred high-level payroll preset. Use DE_STANDARD_EMPLOYEE_STATUTORY for a normal German employee with statutory pension, unemployment, health, and care insurance.

Land'DE' | 'AT' | 'US' | 'CH' | 'CA' | 'AU' | 'UK' | 'IE'

Country code for the calculation.

Stjahrinteger

Tax year.

Currency'EUR' | 'USD' | 'CHF' | 'CAD' | 'AUD' | 'GBP'

Display currency / calculation currency code.

LZZ1 | 2 | 3 | 4

Payroll period identifier for the calculation. Values: 1=year, 2=month, 3=week, 4=day. All salary and payroll monetary inputs must be for this period, not automatically annualized.

Modus1 | 2 | 3

Calculation mode. Use 1 for one person, 2 for two persons, and 3 for the German TaxSim capped real-splitting simulation.

Faktornumber

Global factor for factor-based tax class handling.

KinderFRBnumber

Top-level child allowance, child count, dependent count, or child-credit factor for the calculation. DE uses allowance-style factors; AT/CH/US and other systems use country-specific child/dependent meanings where supported.

KinderPVAinteger

Total child count relevant for German long-term care insurance contribution logic. Leave 0 outside German care-insurance scenarios unless a country-specific child workflow explicitly requires it.

Kindergeldinteger

Child benefit amount in minor units for the selected calculation context. Leave 0 for standard payroll estimates unless explicitly modeling child benefit or a country-specific dependent benefit.

Example request

{
  "country": "DE",
  "tax_year": 2026,
  "age": 35,
  "gross_salary": {
    "amount": 60000,
    "currency": "EUR",
    "period": "annual"
  },
  "location": {
    "federal_state": "BE"
  },
  "employee_type": "standard_statutory_employee",
  "payroll_preset": "DE_STANDARD_EMPLOYEE_STATUTORY",
  "tax": {
    "tax_class": 1,
    "church_tax": false,
    "child_allowance_factor": 0
  },
  "social_security": {
    "pension_insurance": "statutory",
    "unemployment_insurance": "statutory",
    "health_insurance": "statutory",
    "health_additional_contribution_percent": 2.9,
    "long_term_care_insurance": "statutory",
    "children_for_care_insurance": 0
  }
}

Response

berechne response

calculated_atstring date-time required

UTC timestamp when this response was assembled.

contract_versionstring required

Obolus public contract version used to shape this response.

tax_data_versionstring required

Tax-data or backend-engine revision used for this response.

method_versionstring required

Calculation method or benchmark method version used for this response.

orientation_notestring required

Reminder that the result is an orientation estimate, not professional advice.

faktornumber

Tax factor used for German tax class IV factor workflows when applicable.

source_urlstring required

Canonical Obolus URL for the matching interactive calculator.

visual_reportstring required

Deep link to the interactive report or calculator view.

warningsstring[] required

Non-blocking warnings about suspicious inputs, such as annual gross sent with monthly LZZ, scaled German Zusatzbeitrag values, or raw German insurance combinations that may be intentional for non-standard cases.

Changes

No recorded changes to this operation across all 1 revision of this API.