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

ageinteger

Adult age in the selected tax year.

regionsobject

Country-keyed tax regions, for example CH: ZH. Omitted regions use country defaults, reported in calculation_profile.

salary_ctinteger

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_grossnumber

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_assessmentboolean

Broad joint filing / joint assessment assumption for comparable country-level estimates. For precise country-specific filing details, use berechne.

childreninteger

Number of children or dependents used as a broad comparison assumption. Country-specific child allowance and credit rules are simplified for comparability.

countriesstring[] 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.

Example request

{
  "salary_ct": 5000000,
  "gross_mode": "shared_gross",
  "period": "annual",
  "person_type": "single",
  "joint_assessment": false,
  "children": 0,
  "tax_year": 2026,
  "countries": [
    "US",
    "IE",
    "DE",
    "CA"
  ],
  "currency": "EUR"
}

Response

taxcompare 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.

source_urlstring required

Canonical Obolus TaxCompare URL for this result.

visual_reportstring required

Deep link to TaxCompare with the tool input, countries, year, and agent attribution prefilled.

assumptionsobject required

Normalized comparison inputs used for the calculation, including age, tax year, countries, gross mode, salary, and household assumptions.

warningsstring[] 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_inputsobject 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_versionstring

Editorial benchmark method version used when comparison_basis is local_median_gross.

benchmark_sourcesobject

Country-level benchmark source metadata used in local_median_gross mode, keyed by country code.

Changes

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