{"openapi":"3.1.0","info":{"title":"Gross-to-Net Salary Calculator (Germany & UK)","summary":"Net pay to the cent, every deduction and the employer's cost for Germany and the UK, computed with the official payroll algorithms and matching 1,552 of 1,552 official test cases.","description":"**Net salary to the cent, not an approximation.** Send a gross salary and a short profile, get back the net pay, every employee deduction and every employer contribution on its own line, each with the rule applied and the official source. Also works backwards (net → gross) and side by side across countries and years.\n\nBuilt for job boards and salary-comparison sites that show \"net per month\", relocation and mobility platforms, employer-of-record and contractor-vs-employee calculators, offer-letter and HR tools, and budgeting apps (also available as an MCP server for AI agents). Payroll rules change every year; this API keeps each country and tax year callable so you don't have to maintain them.\n\n**Coverage**\n- **Germany 2025 and 2026**: wage tax from our own implementation of the BMF *Programmablaufplan* (tax classes I–VI, child allowances, factor procedure for class IV, annual tax allowance, age relief), solidarity surcharge, church tax (8 % in BY/BW, 9 % elsewhere), health insurance with the fund's add-on rate, long-term care with the childless surcharge, child discounts and the Saxony split, pension and unemployment insurance with the contribution ceilings, and the employer's shares plus the insolvency levy.\n- **United Kingdom 2025-26 and 2026-27**: PAYE income tax with any tax code (L, K, BR, D0–D3, NT, 0T, week 1/month 1, cumulative with pay and tax to date), Scottish (S) and Welsh (C) rates, and Class 1 National Insurance for categories A, B, C, H, J, M, V and Z with the employer's NICs.\n\n**Proven, not claimed.** The German engine matches 320 of 320 labelled cases from the BMF's own wage-tax calculator (2025 and 2026), and the UK engine matches all 1,232 rows of HMRC's official payroll test data (336 PAYE rows and 896 National Insurance rows). The pass rates are measured on every change and published on this page and in the dev log.\n\n**Endpoints**\n- `POST /net` – gross → net with a line-by-line breakdown, employer cost, annualised totals, notes and sources.\n- `POST /gross` – net → gross: the smallest gross pay that yields at least the target net, using the same engine.\n- `POST /compare` – up to 8 scenarios (countries, years, profiles) side by side.\n- `GET /parameters` – the thresholds and rates in use for a country and year, with sources.\n- `GET /countries` – coverage, supported years, periods and profile fields, and what is planned.\n\n**Example** – `POST /net` with `{\"country\": \"DE\", \"year\": 2026, \"gross\": 4500, \"period\": \"month\", \"de\": {\"tax_class\": 1, \"state\": \"BY\", \"church\": true}}`:\n```json\n{\"country\": \"DE\", \"year\": 2026, \"currency\": \"EUR\", \"gross\": 4500.0, \"net\": 2819.08,\n \"employee_deductions\": 1680.92, \"employer_cost\": 5458.5, \"deduction_rate\": 37.35,\n \"lines\": [\n  {\"key\": \"income_tax\", \"label\": \"Lohnsteuer (wage tax)\", \"amount\": 650.16, \"payer\": \"employee\",\n   \"rule\": \"PAP 2026: tax class 1, 0 child allowances, pay period month\", \"source\": \"BMF: Programmablaufplan … 2026\"},\n  {\"key\": \"church_tax\", \"label\": \"Kirchensteuer\", \"amount\": 52.01, \"payer\": \"employee\", \"rate\": 8.0,\n   \"rule\": \"8 % (Bayern) of the church-tax base 650.16 EUR …\"},\n  {\"key\": \"health_insurance\", \"amount\": 393.75, \"payer\": \"employee\", \"rate\": 8.75, \"base\": 4500.0,\n   \"rule\": \"14.6 % general rate + 2.9 % add-on, split equally\"},\n  {\"key\": \"care_insurance\", \"amount\": 108.0, \"payer\": \"employee\",\n   \"rule\": \"3.6 % total; +0.6 % childless surcharge paid by the employee (age 23+, no children)\"}],\n \"disclaimer\": \"Estimate for offers, budgeting and comparisons, not a payroll run …\"}\n```\nNot yet supported and rejected with a clear 400 instead of approximated: German Minijob/Midijob pay (up to 2,000 EUR/month), private health insurance, employees above retirement age; UK student loans and pensions. Results are estimates, not a payroll run or tax advice.","version":"1.0.0"},"servers":[{"url":"https://syntropicapi.com"}],"paths":{"/v1/salary-net/net":{"post":{"summary":"Gross to net: net pay, deductions and employer cost","description":"Computes net pay from gross pay for one pay period with the country's official payroll algorithm.\nReturns every employee deduction and employer contribution as a line with the rule applied and its source,\nthe employer's total cost, annualised figures and the assumptions made.","operationId":"calculate_net_salary","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/salary-net/gross":{"post":{"summary":"Net to gross: the gross pay needed for a target net","description":"Finds the smallest gross pay (to the cent) whose net pay reaches the target, by bisection over the same engine\nas /net. Returns the full breakdown for that gross pay and the remaining difference to the target.","operationId":"calculate_gross_salary","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrossIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrossOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/salary-net/compare":{"post":{"summary":"Compare net pay across countries, years and profiles","description":"Runs up to 8 gross-to-net scenarios and returns them side by side: net, deductions, employer cost and the\nsplit into income tax and social contributions. Amounts stay in each country's currency (no FX conversion).","operationId":"compare_net_salaries","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/salary-net/parameters":{"get":{"summary":"Thresholds and rates used for a country and year","description":"Allowances, tax bands, contribution rates and ceilings the engine uses for the country and year, each with\nits official source.","operationId":"get_payroll_parameters","parameters":[{"name":"country","in":"query","required":true,"schema":{"enum":["DE","UK","GB"],"type":"string","description":"DE or UK (GB is accepted)","title":"Country"},"description":"DE or UK (GB is accepted)"},{"name":"year","in":"query","required":false,"schema":{"type":"integer","maximum":2100,"minimum":2000,"description":"Tax year (UK: start year, 2026 = 2026-27)","default":2026,"title":"Year"},"description":"Tax year (UK: start year, 2026 = 2026-27)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParametersOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/salary-net/countries":{"get":{"summary":"Countries, tax years and profile fields covered","description":"Coverage: which countries and tax years are available, which pay periods and profile fields they accept, the\nofficial test data each engine is checked against, and which countries are planned next.","operationId":"list_salary_countries","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountriesOut"}}}}}}}},"components":{"schemas":{"Annual":{"properties":{"gross":{"type":"number","title":"Gross","description":"Gross × periods per year"},"net":{"type":"number","title":"Net","description":"Net × periods per year"},"employer_cost":{"type":"number","title":"Employer Cost","description":"Employer cost × periods per year"}},"type":"object","required":["gross","net","employer_cost"],"title":"Annual"},"CompareIn":{"properties":{"scenarios":{"items":{"$ref":"#/components/schemas/NetIn"},"type":"array","maxItems":8,"minItems":1,"title":"Scenarios","description":"Up to 8 gross-to-net scenarios"}},"additionalProperties":false,"type":"object","required":["scenarios"],"title":"CompareIn"},"CompareOut":{"properties":{"rows":{"items":{"$ref":"#/components/schemas/CompareRow"},"type":"array","title":"Rows"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes"},"disclaimer":{"type":"string","title":"Disclaimer"}},"type":"object","required":["rows","notes","disclaimer"],"title":"CompareOut"},"CompareRow":{"properties":{"label":{"type":"string","title":"Label","description":"Country, tax year and main profile setting"},"country":{"type":"string","title":"Country"},"tax_year":{"type":"string","title":"Tax Year"},"currency":{"type":"string","title":"Currency"},"period":{"type":"string","title":"Period"},"gross":{"type":"number","title":"Gross"},"net":{"type":"number","title":"Net"},"employee_deductions":{"type":"number","title":"Employee Deductions"},"employer_cost":{"type":"number","title":"Employer Cost"},"deduction_rate":{"type":"number","title":"Deduction Rate"},"annual_net":{"type":"number","title":"Annual Net"},"income_tax":{"type":"number","title":"Income Tax","description":"Income/wage tax plus surcharges (solidarity, church)"},"social_contributions":{"type":"number","title":"Social Contributions","description":"Employee social insurance or National Insurance"}},"type":"object","required":["label","country","tax_year","currency","period","gross","net","employee_deductions","employer_cost","deduction_rate","annual_net","income_tax","social_contributions"],"title":"CompareRow"},"CountriesOut":{"properties":{"countries":{"items":{"$ref":"#/components/schemas/CountryInfo"},"type":"array","title":"Countries"}},"type":"object","required":["countries"],"title":"CountriesOut"},"CountryInfo":{"properties":{"country":{"type":"string","title":"Country","description":"Country code"},"name":{"type":"string","title":"Name"},"status":{"type":"string","enum":["available","planned"],"title":"Status"},"currency":{"type":"string","title":"Currency"},"years":{"items":{"type":"integer"},"type":"array","title":"Years","description":"Supported tax years (UK: start year)"},"periods":{"items":{"type":"string"},"type":"array","title":"Periods"},"profile_fields":{"items":{"type":"string"},"type":"array","title":"Profile Fields"},"conformance":{"type":"string","title":"Conformance","description":"Ground truth the engine is tested against"}},"type":"object","required":["country","name","status","currency","years","periods","profile_fields","conformance"],"title":"CountryInfo"},"DEProfileIn":{"properties":{"tax_class":{"type":"integer","maximum":6.0,"minimum":1.0,"title":"Tax Class","description":"Steuerklasse 1-6 (I single, II single parent, III/V married split, IV married, VI second job)","default":1},"state":{"type":"string","maxLength":2,"minLength":2,"title":"State","description":"Bundesland code of the workplace: BW, BY, BE, BB, HB, HH, HE, MV, NI, NW, RP, SL, SN, ST, SH, TH (church-tax rate; SN = Saxony care-insurance split)","default":"NW"},"church":{"type":"boolean","title":"Church","description":"Member of a church that levies church tax","default":false},"children":{"type":"integer","maximum":20.0,"minimum":0.0,"title":"Children","description":"Children under 25: care-insurance discounts from the 2nd child and, by default, the child allowances","default":0},"child_allowances":{"anyOf":[{"type":"number","maximum":20.0,"minimum":0.0},{"type":"null"}],"title":"Child Allowances","description":"Kinderfreibeträge on the tax card in 0.5 steps (default: children); 0.5 per child when the parents split them"},"parent":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Parent","description":"Has ever had a child, so no childless surcharge in care insurance (default: children > 0)"},"birth_year":{"anyOf":[{"type":"integer","maximum":2015.0,"minimum":1900.0},{"type":"null"}],"title":"Birth Year","description":"Year of birth: childless surcharge only from 23, age relief from 65; 67+ is rejected"},"health_insurance":{"type":"string","enum":["statutory","private"],"title":"Health Insurance","description":"Only statutory health insurance is supported so far","default":"statutory"},"health_insurance_addon_rate":{"anyOf":[{"type":"number","maximum":10.0,"minimum":0.0},{"type":"null"}],"title":"Health Insurance Addon Rate","description":"The fund's add-on rate (Zusatzbeitrag) in %, e.g. 2.9; default the official average of the year"},"factor":{"anyOf":[{"type":"number","exclusiveMaximum":1.0,"exclusiveMinimum":0.0},{"type":"null"}],"title":"Factor","description":"Faktorverfahren factor for tax class IV, three decimals (e.g. 0.912)"},"annual_tax_allowance":{"type":"number","maximum":1000000.0,"minimum":0.0,"title":"Annual Tax Allowance","description":"Tax allowance (Freibetrag) on the tax card, EUR per year","default":0}},"additionalProperties":false,"type":"object","title":"DEProfileIn"},"GrossIn":{"properties":{"country":{"type":"string","enum":["DE","UK","GB"],"title":"Country","description":"DE or UK (GB is accepted as UK)"},"year":{"type":"integer","maximum":2100.0,"minimum":2000.0,"title":"Year","description":"Tax year. UK: the year the tax year starts in (2026 = 2026-27)","default":2026},"period":{"type":"string","enum":["year","month","week","day","fortnight","four_weeks"],"title":"Period","description":"Pay period of the amount: year, month, week, day (DE only), fortnight or four_weeks (UK only)","default":"month"},"de":{"anyOf":[{"$ref":"#/components/schemas/DEProfileIn"},{"type":"null"}],"description":"German profile (used when country is DE)"},"uk":{"anyOf":[{"$ref":"#/components/schemas/UKProfileIn"},{"type":"null"}],"description":"UK profile (used when country is UK)"},"net":{"type":"number","maximum":5000000.0,"exclusiveMinimum":0.0,"title":"Net","description":"Target net pay for the period, in EUR (DE) or GBP (UK)","examples":[3000]}},"additionalProperties":false,"type":"object","required":["country","net"],"title":"GrossIn"},"GrossOut":{"properties":{"country":{"type":"string","title":"Country","description":"DE or UK"},"year":{"type":"integer","title":"Year","description":"Tax year (UK: year the tax year starts)"},"tax_year":{"type":"string","title":"Tax Year","description":"Tax year label, e.g. 2026 or 2026-27"},"period":{"type":"string","title":"Period","description":"Pay period of all amounts"},"currency":{"type":"string","title":"Currency","description":"EUR or GBP"},"gross":{"type":"number","title":"Gross","description":"Gross pay for the period"},"net":{"type":"number","title":"Net","description":"Net pay: gross minus all employee deductions"},"employee_deductions":{"type":"number","title":"Employee Deductions","description":"Sum of the employee lines"},"employer_contributions":{"type":"number","title":"Employer Contributions","description":"Sum of the employer lines"},"employer_cost":{"type":"number","title":"Employer Cost","description":"Gross plus employer contributions"},"deduction_rate":{"type":"number","title":"Deduction Rate","description":"Employee deductions in % of gross"},"annual":{"$ref":"#/components/schemas/Annual","description":"The period's figures scaled to a year (periods per year × amount)"},"lines":{"items":{"$ref":"#/components/schemas/Line"},"type":"array","title":"Lines","description":"Every deduction and contribution with rule and source"},"profile":{"additionalProperties":true,"type":"object","title":"Profile","description":"The profile as applied, including defaults that were filled in"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"Assumptions and what is not included"},"sources":{"items":{"$ref":"#/components/schemas/Source"},"type":"array","title":"Sources","description":"Official publications used"},"disclaimer":{"type":"string","title":"Disclaimer"},"target_net":{"type":"number","title":"Target Net","description":"The net pay that was asked for"},"difference":{"type":"number","title":"Difference","description":"net - target_net (0 when the target is reachable to the cent)"}},"type":"object","required":["country","year","tax_year","period","currency","gross","net","employee_deductions","employer_contributions","employer_cost","deduction_rate","annual","lines","profile","notes","sources","disclaimer","target_net","difference"],"title":"GrossOut"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Line":{"properties":{"key":{"type":"string","title":"Key","description":"income_tax, solidarity_surcharge, church_tax, health_insurance, care_insurance, pension_insurance, unemployment_insurance, insolvency_levy, national_insurance"},"label":{"type":"string","title":"Label","description":"Name of the deduction in the country's terms"},"amount":{"type":"number","title":"Amount","description":"Amount for the period (negative = refund on the UK cumulative basis)"},"payer":{"type":"string","enum":["employee","employer"],"title":"Payer","description":"Who bears it: employee (deducted from gross) or employer (on top)"},"rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rate","description":"Rate in % of base, where a single rate applies"},"base":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Base","description":"Amount the rate applies to (after contribution ceilings) or taxable pay"},"rule":{"type":"string","title":"Rule","description":"The rule applied, in words"},"source":{"type":"string","title":"Source","description":"Official source of the rule and rate"}},"type":"object","required":["key","label","amount","payer","rule","source"],"title":"Line"},"NetIn":{"properties":{"country":{"type":"string","enum":["DE","UK","GB"],"title":"Country","description":"DE or UK (GB is accepted as UK)"},"year":{"type":"integer","maximum":2100.0,"minimum":2000.0,"title":"Year","description":"Tax year. UK: the year the tax year starts in (2026 = 2026-27)","default":2026},"period":{"type":"string","enum":["year","month","week","day","fortnight","four_weeks"],"title":"Period","description":"Pay period of the amount: year, month, week, day (DE only), fortnight or four_weeks (UK only)","default":"month"},"de":{"anyOf":[{"$ref":"#/components/schemas/DEProfileIn"},{"type":"null"}],"description":"German profile (used when country is DE)"},"uk":{"anyOf":[{"$ref":"#/components/schemas/UKProfileIn"},{"type":"null"}],"description":"UK profile (used when country is UK)"},"gross":{"type":"number","maximum":10000000.0,"exclusiveMinimum":0.0,"title":"Gross","description":"Gross pay for the period, in EUR (DE) or GBP (UK)","examples":[4500]}},"additionalProperties":false,"type":"object","required":["country","gross"],"title":"NetIn"},"NetOut":{"properties":{"country":{"type":"string","title":"Country","description":"DE or UK"},"year":{"type":"integer","title":"Year","description":"Tax year (UK: year the tax year starts)"},"tax_year":{"type":"string","title":"Tax Year","description":"Tax year label, e.g. 2026 or 2026-27"},"period":{"type":"string","title":"Period","description":"Pay period of all amounts"},"currency":{"type":"string","title":"Currency","description":"EUR or GBP"},"gross":{"type":"number","title":"Gross","description":"Gross pay for the period"},"net":{"type":"number","title":"Net","description":"Net pay: gross minus all employee deductions"},"employee_deductions":{"type":"number","title":"Employee Deductions","description":"Sum of the employee lines"},"employer_contributions":{"type":"number","title":"Employer Contributions","description":"Sum of the employer lines"},"employer_cost":{"type":"number","title":"Employer Cost","description":"Gross plus employer contributions"},"deduction_rate":{"type":"number","title":"Deduction Rate","description":"Employee deductions in % of gross"},"annual":{"$ref":"#/components/schemas/Annual","description":"The period's figures scaled to a year (periods per year × amount)"},"lines":{"items":{"$ref":"#/components/schemas/Line"},"type":"array","title":"Lines","description":"Every deduction and contribution with rule and source"},"profile":{"additionalProperties":true,"type":"object","title":"Profile","description":"The profile as applied, including defaults that were filled in"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"Assumptions and what is not included"},"sources":{"items":{"$ref":"#/components/schemas/Source"},"type":"array","title":"Sources","description":"Official publications used"},"disclaimer":{"type":"string","title":"Disclaimer"}},"type":"object","required":["country","year","tax_year","period","currency","gross","net","employee_deductions","employer_contributions","employer_cost","deduction_rate","annual","lines","profile","notes","sources","disclaimer"],"title":"NetOut"},"ParameterRow":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"value":{"type":"number","title":"Value"},"unit":{"type":"string","title":"Unit"},"source":{"type":"string","title":"Source"}},"type":"object","required":["key","label","value","unit","source"],"title":"ParameterRow"},"ParametersOut":{"properties":{"country":{"type":"string","title":"Country"},"year":{"type":"integer","title":"Year"},"tax_year":{"type":"string","title":"Tax Year"},"currency":{"type":"string","title":"Currency"},"parameters":{"items":{"$ref":"#/components/schemas/ParameterRow"},"type":"array","title":"Parameters"}},"type":"object","required":["country","year","tax_year","currency","parameters"],"title":"ParametersOut"},"Source":{"properties":{"name":{"type":"string","title":"Name"},"url":{"type":"string","title":"Url"},"license":{"type":"string","title":"License"}},"type":"object","required":["name","url","license"],"title":"Source"},"UKProfileIn":{"properties":{"region":{"type":"string","enum":["england","northern-ireland","scotland","wales"],"title":"Region","description":"Where the employee lives for income tax (Scotland and Wales set their own rates)","default":"england"},"tax_code":{"anyOf":[{"type":"string","maxLength":12},{"type":"null"}],"title":"Tax Code","description":"PAYE tax code, e.g. 1257L, S1257L, C1257L, K475, BR, D0, NT, 0T, '1257L M1' (default: 1257L with the region's prefix)"},"ni_category":{"type":"string","enum":["A","B","C","H","J","M","V","Z"],"title":"Ni Category","description":"National Insurance category letter (A standard, B reduced, C over State Pension age, H apprentice <25, J deferred, M under 21, V veteran, Z under 21 deferred)","default":"A"},"period_number":{"anyOf":[{"type":"integer","maximum":52.0,"minimum":1.0},{"type":"null"}],"title":"Period Number","description":"Tax week or month number for the cumulative basis; omit for a stand-alone (week 1/month 1) period"},"previous_pay":{"anyOf":[{"type":"number","maximum":100000000.0,"minimum":0.0},{"type":"null"}],"title":"Previous Pay","description":"Taxable pay in this tax year before this period (cumulative basis)"},"previous_tax":{"anyOf":[{"type":"number","maximum":100000000.0,"minimum":-10000000.0},{"type":"null"}],"title":"Previous Tax","description":"Tax deducted in this tax year before this period (cumulative basis)"}},"additionalProperties":false,"type":"object","title":"UKProfileIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"security":[{"ApiKey":[]}]}