{"openapi":"3.1.0","info":{"title":"frontaliere.tax calculator API","version":"1.0.0","description":"Net salary of people resident in Italy who work as employees in Ticino, Graubunden or Valais. The same calculation as the website. Not tax advice. Agent guide: https://frontaliere.tax/agents.md. The API computes on Cloudflare servers and stores nothing; prefer POST to keep figures out of URLs."},"servers":[{"url":"https://frontaliere.tax"}],"paths":{"/api/v1/calculate":{"get":{"operationId":"calculateNetSalary","summary":"Calculate the net salary of an Italy-Switzerland cross-border worker","parameters":[{"name":"comune","in":"query","required":true,"schema":{"type":"string","description":"Codice catastale of the Italian comune of tax residence on 1 January of the income year, e.g. C933 for Como. Any Italian comune is accepted; the 518 within 20 km of the border are the frontaliere cases. Look it up with find_comune or /api/v1/comuni?q=."}},{"name":"grossMonth","in":"query","required":false,"schema":{"type":"number","description":"Gross monthly salary in CHF, before any deduction. Give this or grossYear.","minimum":0}},{"name":"grossYear","in":"query","required":false,"schema":{"type":"number","description":"Gross salary in CHF actually received in the year. Takes precedence over grossMonth.","minimum":0}},{"name":"payments","in":"query","required":false,"schema":{"type":"integer","description":"Salary payments per year. It matters even with grossYear: it decides how the 13th is withheld in Graubunden.","enum":[12,13,14],"default":13}},{"name":"monthsWorked","in":"query","required":false,"schema":{"type":"integer","description":"Months of Swiss employment in the year. With fewer than 12, give the gross actually received; the canton annualises it only to pick the tariff rate.","minimum":1,"maximum":12,"default":12}},{"name":"year","in":"query","required":false,"schema":{"type":"integer","description":"Income year. The Italian return filed in year N covers income of year N-1. 2026 parameters are provisional.","enum":[2024,2025,2026],"default":2025}},{"name":"canton","in":"query","required":false,"schema":{"type":"string","description":"Swiss canton of work: Ticino, Graubunden or Valais.","enum":["TI","GR","VS"],"default":"TI"}},{"name":"dailyReturn","in":"query","required":false,"schema":{"type":"boolean","description":"Whether the worker returns home to Italy every day. false is out of scope: weekly commuters are taxed on notional pay, which this calculator does not model.","default":true}},{"name":"workedBefore","in":"query","required":false,"schema":{"type":"boolean","description":"Worked as a cross-border worker in Ticino, Graubunden or Valais at any time between 31.12.2018 and 17.07.2023. Decides old (case A) versus new (case B) frontaliere.","default":false}},{"name":"oldLists","in":"query","required":false,"schema":{"type":"boolean","description":"Only with workedBefore: whether the comune was in the old cantonal lists of frontaliere comuni. Defaults to false for comuni in the Omnibus annexes and true otherwise."}},{"name":"maritalStatus","in":"query","required":false,"schema":{"type":"string","description":"For the Swiss withholding tariff code.","enum":["single","married"],"default":"single"}},{"name":"spouseWorks","in":"query","required":false,"schema":{"type":"boolean","description":"Married, and the spouse also works.","default":false}},{"name":"children","in":"query","required":false,"schema":{"type":"integer","description":"Children counted for the Swiss withholding tariff code.","minimum":0,"maximum":9,"default":0}},{"name":"churchTax","in":"query","required":false,"schema":{"type":"boolean","description":"Swiss church tax. Ticino and Valais publish only tariffs without it.","default":false}},{"name":"age","in":"query","required":false,"schema":{"type":"integer","description":"Age, which sets the minimum occupational pension (LPP) savings rate.","minimum":17,"maximum":70,"default":40}},{"name":"health","in":"query","required":false,"schema":{"type":"string","description":"Italian national health service or Swiss LAMal insurance.","enum":["SSN","LAMal"],"default":"SSN"}},{"name":"lamalPremium","in":"query","required":false,"schema":{"type":"number","description":"Monthly LAMal premium in CHF, used when health is LAMal.","minimum":0,"default":350}},{"name":"manualQst","in":"query","required":false,"schema":{"type":"number","description":"Monthly Swiss withholding tax in CHF read from the payslip. When given it replaces the tariff tables.","minimum":0}},{"name":"familyAllowances","in":"query","required":false,"schema":{"type":"number","description":"Yearly Swiss family allowances in CHF, paid with the salary on top of the gross. Subject to Swiss withholding, not to contributions, exempt from Italian income tax.","minimum":0,"default":0}},{"name":"otherIncome","in":"query","required":false,"schema":{"type":"number","description":"Other Italian taxable income in EUR.","minimum":0,"default":0}},{"name":"oneriDeducibili","in":"query","required":false,"schema":{"type":"number","description":"Italian deductible charges in EUR.","minimum":0,"default":0}},{"name":"detrazioniAltre","in":"query","required":false,"schema":{"type":"number","description":"Other Italian tax credits in EUR, as already-computed credit amounts.","minimum":0,"default":0}},{"name":"creditMode","in":"query","required":false,"schema":{"type":"string","description":"Foreign tax credit method: reduced is the tax authority practice (art. 165 c. 10 TUIR), full is the line taken by several tax courts.","enum":["reduced","full"],"default":"reduced"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","description":"Language of labels, explanations and warnings in the result.","enum":["it","en"],"default":"it"}}],"responses":{"200":{"description":"The calculation, with every line explained. When the case is out of scope, `case` is null and `out_of_scope` says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"The input was invalid. Every problem is listed at once.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}}}}}}}},"post":{"operationId":"calculateNetSalaryPost","summary":"The same calculation, with the parameters in a JSON body","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["comune"],"properties":{"comune":{"type":"string","description":"Codice catastale of the Italian comune of tax residence on 1 January of the income year, e.g. C933 for Como. Any Italian comune is accepted; the 518 within 20 km of the border are the frontaliere cases. Look it up with find_comune or /api/v1/comuni?q=."},"grossMonth":{"type":"number","description":"Gross monthly salary in CHF, before any deduction. Give this or grossYear.","minimum":0},"grossYear":{"type":"number","description":"Gross salary in CHF actually received in the year. Takes precedence over grossMonth.","minimum":0},"payments":{"type":"integer","description":"Salary payments per year. It matters even with grossYear: it decides how the 13th is withheld in Graubunden.","enum":[12,13,14],"default":13},"monthsWorked":{"type":"integer","description":"Months of Swiss employment in the year. With fewer than 12, give the gross actually received; the canton annualises it only to pick the tariff rate.","minimum":1,"maximum":12,"default":12},"year":{"type":"integer","description":"Income year. The Italian return filed in year N covers income of year N-1. 2026 parameters are provisional.","enum":[2024,2025,2026],"default":2025},"canton":{"type":"string","description":"Swiss canton of work: Ticino, Graubunden or Valais.","enum":["TI","GR","VS"],"default":"TI"},"dailyReturn":{"type":"boolean","description":"Whether the worker returns home to Italy every day. false is out of scope: weekly commuters are taxed on notional pay, which this calculator does not model.","default":true},"workedBefore":{"type":"boolean","description":"Worked as a cross-border worker in Ticino, Graubunden or Valais at any time between 31.12.2018 and 17.07.2023. Decides old (case A) versus new (case B) frontaliere.","default":false},"oldLists":{"type":"boolean","description":"Only with workedBefore: whether the comune was in the old cantonal lists of frontaliere comuni. Defaults to false for comuni in the Omnibus annexes and true otherwise."},"maritalStatus":{"type":"string","description":"For the Swiss withholding tariff code.","enum":["single","married"],"default":"single"},"spouseWorks":{"type":"boolean","description":"Married, and the spouse also works.","default":false},"children":{"type":"integer","description":"Children counted for the Swiss withholding tariff code.","minimum":0,"maximum":9,"default":0},"churchTax":{"type":"boolean","description":"Swiss church tax. Ticino and Valais publish only tariffs without it.","default":false},"age":{"type":"integer","description":"Age, which sets the minimum occupational pension (LPP) savings rate.","minimum":17,"maximum":70,"default":40},"health":{"type":"string","description":"Italian national health service or Swiss LAMal insurance.","enum":["SSN","LAMal"],"default":"SSN"},"lamalPremium":{"type":"number","description":"Monthly LAMal premium in CHF, used when health is LAMal.","minimum":0,"default":350},"manualQst":{"type":"number","description":"Monthly Swiss withholding tax in CHF read from the payslip. When given it replaces the tariff tables.","minimum":0},"familyAllowances":{"type":"number","description":"Yearly Swiss family allowances in CHF, paid with the salary on top of the gross. Subject to Swiss withholding, not to contributions, exempt from Italian income tax.","minimum":0,"default":0},"otherIncome":{"type":"number","description":"Other Italian taxable income in EUR.","minimum":0,"default":0},"oneriDeducibili":{"type":"number","description":"Italian deductible charges in EUR.","minimum":0,"default":0},"detrazioniAltre":{"type":"number","description":"Other Italian tax credits in EUR, as already-computed credit amounts.","minimum":0,"default":0},"creditMode":{"type":"string","description":"Foreign tax credit method: reduced is the tax authority practice (art. 165 c. 10 TUIR), full is the line taken by several tax courts.","enum":["reduced","full"],"default":"reduced"},"lang":{"type":"string","description":"Language of labels, explanations and warnings in the result.","enum":["it","en"],"default":"it"}}}}}},"responses":{"200":{"description":"The calculation, with every line explained. When the case is out of scope, `case` is null and `out_of_scope` says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"The input was invalid. Every problem is listed at once.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/v1/comuni":{"get":{"operationId":"findComune","summary":"Find an Italian comune and its codice catastale","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"description":"Name of the comune, or the start of it."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}],"responses":{"200":{"description":"Matches, best first.","content":{"application/json":{"schema":{"type":"object","properties":{"matches":{"type":"array","items":{"type":"object","properties":{"codice":{"type":"string"},"comune":{"type":"string"},"provincia":{"type":"string"},"within_20km_band":{"type":"boolean"},"omnibus_annex":{"type":["integer","null"]},"modelled_region":{"type":"boolean"}}}}}}}}}}}}},"components":{"schemas":{"Result":{"type":"object","properties":{"income_year":{"type":"integer"},"case":{"type":["object","null"],"properties":{"id":{"enum":["A","B","C","D"]},"description":{"type":"string"}}},"out_of_scope":{"type":["object","null"]},"summary":{"type":"object","description":"Headline figures: net per year and per month in EUR and CHF, gross, Swiss contributions and withholding, Italian tax, health cost, effective rate, exchange rate."},"omnibus_option":{"type":["object","null"],"description":"Present when the 25% option is available: both nets and the better choice."},"lines":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"group":{"type":"string"},"label":{"type":"string"},"amount_chf":{"type":["number","null"]},"amount_eur":{"type":["number","null"]},"explanation":{"type":"string"},"formula":{"type":["string","null"]},"legal_reference":{"type":["string","null"]}}}},"for_730":{"type":"object","description":"Figures for the Italian 730 return."},"warnings":{"type":"array","items":{"type":"string"}},"calculator_url":{"type":"string","description":"Opens the calculator with these inputs filled in."},"disclaimer":{"type":"string"}}}}}}