---
title: "Compare annual gross, net pay, taxes, and employee social contributions across two or more supported countries. Use shared_gross for the same offer and local_median_gross for country-market benchmarks. Provide tax_year and at least two countries. Use berechne for detailed single-country payroll."
method: POST
path: "/api/taxcompare"
tags: ["tools"]
---

# Compare annual gross, net pay, taxes, and employee social contributions across two or more supported countries. Use shared_gross for the same offer and local_median_gross for country-market benchmarks. Provide tax_year and at least two countries. Use berechne for detailed single-country payroll.

`POST /api/taxcompare`

## Request

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

## Request body

- TaxcompareRequest: Input for a multi-country salary comparison. Use at least two countries, tax_year, and either salary_ct/annual_gross for shared_gross or local_median_gross without a salary. Results are annual major-currency estimates.
  - `age` integer: Adult age in the selected tax year.
  - `regions` object: Country-keyed tax regions, for example CH: ZH. Omitted regions use country defaults, reported in calculation_profile.
  - `salary_ct` integer: Preferred salary input for MCP calls. Salary in minor units for the selected period, for example 5000000 for EUR 50,000. With period=annual this is annual salary; with period=monthly this is monthly salary and Obolus annualizes it for the comparison. Required for shared_gross mode unless annual_gross is provided as a legacy alias.
  - `annual_gross` number: Backward-compatible annual gross salary alias in major currency units, not cents. Prefer salary_ct. Example: 50000 means 50,000 in the selected currency. Required for shared_gross mode only when salary_ct is not provided; optional and ignored when omitted for local_median_gross.
  - `gross_mode` 'shared_gross' | 'local_median_gross': Comparison basis. Use shared_gross for the same user-provided annual gross across all countries. Use local_median_gross for country-specific editorial median gross benchmarks. Defaults to shared_gross when omitted.
  - `period` 'annual' | 'monthly': Period for salary_ct. Use annual when salary_ct is the annual gross salary. Use monthly when salary_ct is one monthly gross salary; taxcompare annualizes it before comparing countries. annual_gross is always annual and ignores this field.
  - `person_type` 'single' | 'married': Broad household assumption for comparison. single maps to joint_assessment=false; married maps to joint_assessment=true unless joint_assessment is provided explicitly. For precise country-specific filing details, use berechne.
  - `joint_assessment` boolean: Broad joint filing / joint assessment assumption for comparable country-level estimates. For precise country-specific filing details, use berechne.
  - `children` integer: Number of children or dependents used as a broad comparison assumption. Country-specific child allowance and credit rules are simplified for comparability.
  - `tax_year` union, required: Tax year, for example 2026. The same tax year is applied to every selected country.
    - string
    - integer
  - `countries` string[], required: List of country tax systems to compare. Use at least two countries for a comparison. Supported values: DE, AT, CH, US, UK, IE, CA, AU.
  - `currency` 'eur' | 'usd' | 'chf' | 'cad' | 'aud' | 'gbp' | 'EUR' | 'USD' | 'CHF' | 'CAD' | 'AUD' | 'GBP', required: Input and output currency: EUR, USD, CHF, CAD, AUD, GBP, or lower-case equivalents. Results normalize currency codes to lower-case. Unlike berechne, taxcompare prefers salary_ct for salary input and returns major currency units.

## Response `200`

taxcompare response

- TaxcompareResponse: Annual country comparison response. Amounts are returned in major currency units in the requested lower-case currency, not cents. Results are meant for cross-country comparison; use berechne for detailed single-country payroll output.
  - `calculated_at` string, date-time, required: UTC timestamp when this response was assembled.
  - `contract_version` string, required: Obolus public contract version used to shape this response.
  - `tax_data_version` string, required: Tax-data or backend-engine revision used for this response.
  - `method_version` string, required: Calculation method or benchmark method version used for this response.
  - `orientation_note` string, required: Reminder that the result is an orientation estimate, not professional advice.
  - `tax_year` union, required: Tax year actually used for every country result.
    - string
    - integer
  - `source_url` string, required: Canonical Obolus TaxCompare URL for this result.
  - `visual_report` string, required: Deep link to TaxCompare with the tool input, countries, year, and agent attribution prefilled.
  - `localized_cta` object, required: Localized labels for opening the visual TaxCompare report.
    - `de` string, required: German CTA for the visual report link.
    - `en` string, required: English CTA for the visual report link.
    - `tr` string: Turkish CTA for the visual report link.
  - `summary` object, required: Normalized annual major-unit amounts for every country result. Use key and country together to render stable comparison cards or tables.
    - `amounts` object[], required: Normalized monetary amounts in major currency units. Each item has key, amount, currency, and period; taxcompare items also identify country.
      - `key` 'gross_income' | 'net_income' | 'taxes' | 'social_contributions' | 'total_deductions', required: Country-neutral metric key: gross income, net income, taxes, social contributions, or total deductions.
      - `amount` number, required: Amount in major currency units, such as EUR 37,363.00 rather than cents.
      - `currency` 'EUR' | 'USD' | 'CHF' | 'CAD' | 'AUD' | 'GBP', required: ISO currency code for amount, normalized to uppercase.
      - `period` 'annual' | 'monthly' | 'weekly' | 'daily', required: Period represented by the amount.
      - `country` 'DE' | 'AT' | 'US' | 'CH' | 'CA' | 'AU' | 'UK' | 'IE': Country code for the amount. Present for payroll and comparison results; absent only when the caller supplied no country context.
    - `tax_year` union: Tax year used for the summary when the calculation exposes one.
      - string
      - integer
    - `comparison_basis` 'shared_gross' | 'local_median_gross': Taxcompare basis used for the summary: shared_gross or local_median_gross.
  - `assumptions` object, required: Normalized comparison inputs used for the calculation, including age, tax year, countries, gross mode, salary, and household assumptions.
  - `warnings` string[], required: Non-blocking warnings associated with this comparison.
  - `comparison_basis` 'shared_gross' | 'local_median_gross', required: Basis used for the comparison: shared_gross for the same gross salary in each country, or local_median_gross for country-specific median benchmarks.
  - `gross_inputs` object, required: Annual gross salary input used for each country, keyed by country code and expressed in the selected major currency. In shared_gross mode these values are usually identical; in local_median_gross mode they differ by country benchmark.
  - `benchmark_method_version` string: Editorial benchmark method version used when comparison_basis is local_median_gross.
  - `benchmark_sources` object: Country-level benchmark source metadata used in local_median_gross mode, keyed by country code.
  - `ranking_by_net` object[], required: Countries ranked by estimated annual net salary, highest net first. Use this for 'where do I keep more money' and 'rank by net income' answers.
    - `rank` integer, required: 1-based rank by net salary, highest net first.
    - `country` 'DE' | 'AT' | 'US' | 'CH' | 'CA' | 'AU' | 'UK' | 'IE', required: Country code for this ranked comparison result.
    - `net` number, required: Estimated annual net salary for this country in the requested major currency.
    - `total_deductions` number: Estimated annual tax plus social contributions for this country in the requested major currency.
    - `effective_rate` number: Total deduction rate as percentage points of gross income. Example: 37.7 means 37.7%.
  - `results` object[], required: Country-level comparison results with gross salary, net salary, income/payroll tax, social contributions, total deductions, and effective burden.
    - `country` 'DE' | 'AT' | 'US' | 'CH' | 'CA' | 'AU' | 'UK' | 'IE', required: Country code for this comparison result: DE, AT, CH, US, UK, IE, CA, or AU.
    - `net` number, required: Estimated annual net income after taxes and payroll/social deductions in the selected major currency. This is annual take-home pay, not monthly net.
    - `tax` number, required: Estimated annual tax burden in the selected major currency. Country meanings differ: for example PAYE/PAYG/income tax, federal plus state/provincial components, or withholding tax depending on system.
    - `social_contributions` number, required: Estimated annual employee social contributions or country-specific payroll deductions in the selected major currency. Examples include statutory social insurance, OASDI/Medicare, National Insurance, PRSI, CPP/QPP/EI, Medicare Levy, or Swiss payroll social deductions; private health bills may be outside payroll.
    - `total_deductions` number, required: Estimated annual tax plus employee social contributions/payroll deductions in the selected major currency.
    - `effective_rate` number, required: Combined tax and social contribution burden as percentage points of gross income. Example: 37.7 means 37.7%.
    - `input_annual_gross` number, required: Annual gross salary used for this country in the selected major currency. In local_median_gross mode this is the country-specific benchmark after currency conversion.
    - `input_currency` 'eur' | 'usd' | 'chf' | 'cad' | 'aud' | 'gbp', required: Currency code for the gross input and result values, in lower-case ISO style.
    - `comparison_basis` 'shared_gross' | 'local_median_gross', required: Comparison basis used for this country result.
    - `gross_source` string: Source or mode that produced the gross input, such as shared_user_input for same-salary comparisons or country_median_gross_benchmark for local-market benchmarks.

## Other responses

- `400`: Validation error
- `401`: Valid API key required
- `403`: Requested operation or field requires API key access
- `429`: Rate limit exceeded
- `500`: Server error

---

[API](https://skmtc.dev/obolusfinanz/apis/obolus-finanz-payroll-api.md) · [All operations](https://skmtc.dev/obolusfinanz/apis/obolus-finanz-payroll-api/llms.txt) · [OpenAPI document](https://skmtc.dev/obolusfinanz/apis/obolus-finanz-payroll-api/revisions/6e44241842e1?raw)