Obolus.berechne - Calculate payroll
berechneRead-only
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| LZZ | No | 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. | |
| age | No | Age in the selected tax year. If omitted, the calculation reports the standard age-35 assumption instead of silently hiding the default. | |
| tax | No | Preferred high-level tax assumptions for MCP calls. The adapter maps these to Steuerklasse, Kirche, and Kinderfreibetrag. | |
| Land | No | Country code for the calculation. | |
| Modus | No | Calculation mode. Use 1 for one person, 2 for two persons, and 3 for the German TaxSim capped real-splitting simulation. | |
| Faktor | No | Global factor for factor-based tax class handling. | |
| Stjahr | No | Tax year. | |
| country | No | Preferred high-level country code for MCP calls. For German payroll use DE. The adapter maps this to legacy Land. | |
| Currency | No | Display currency / calculation currency code. | |
| Personen | No | One or two payroll person records. Each person contains salary, tax class, region, insurance, child, and optional special-income inputs. | |
| location | No | Preferred high-level location input. For Germany, federal_state may be a state code such as BE or a full Obolus state name such as Berlin. | |
| tax_year | No | Preferred high-level tax year for MCP calls. The adapter maps this to legacy Stjahr. | |
| KinderFRB | No | 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. | |
| KinderPVA | No | 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. | |
| Kindergeld | No | 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. | |
| gross_salary | No | Preferred high-level gross salary input. Amount is in major currency units, not cents. The adapter maps it to legacy Gehalt_ct minor units and LZZ. | |
| employee_type | No | Preferred high-level German employee type. Use standard_statutory_employee for the common statutory pension, unemployment, health, and care insurance case. | standard_statutory_employee |
| payroll_preset | No | Preferred high-level payroll preset. Use DE_STANDARD_EMPLOYEE_STATUTORY for a normal German employee with statutory pension, unemployment, health, and care insurance. | DE_STANDARD_EMPLOYEE_STATUTORY |
| social_security | No | Preferred high-level German social-security assumptions. Use enums instead of raw Obolus flags. The adapter maps statutory/exempt/private choices to the legacy payroll-engine fields. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| faktor | No | Tax factor used for German tax class IV factor workflows when applicable. | |
| gesamt | No | Combined payroll result across all persons in the calculation. Uses the same country-specific output-code meanings as person1 and person2. | |
| person1 | No | Payroll result for the first person. Interpret stable output codes with the original request Land and the output country-specific usage notes. | |
| person2 | No | Payroll result for the second person. Values are zero or empty when the calculation mode uses only one person. Interpret stable output codes with the original request Land. | |
| summary | Yes | Normalized major-unit amounts for gross income, net income, taxes, social contributions, and total deductions. Use this stable summary for display; raw payroll fields remain available for country-specific detail. | |
| warnings | Yes | 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. | |
| source_url | Yes | Canonical Obolus URL for the matching interactive calculator. | |
| assumptions | Yes | Normalized user-facing assumptions used for the payroll calculation, including country, salary period, location, tax class, church tax, and German social-security choices. Use this to explain what the calculation assumed without exposing raw payroll-engine flags. | |
| calculated_at | Yes | UTC timestamp when this response was assembled. | |
| localized_cta | Yes | Localized call-to-action labels for opening the visual Obolus report link. | |
| visual_report | Yes | Deep link to the interactive report or calculator view. | |
| method_version | Yes | Calculation method or benchmark method version used for this response. | |
| contract_version | Yes | Obolus public contract version used to shape this response. | |
| orientation_note | Yes | Reminder that the result is an orientation estimate, not professional advice. | |
| tax_data_version | Yes | Tax-data or backend-engine revision used for this response. |