{"openapi":"3.1.0","info":{"title":"Helpore household employer cost","version":"1.0.0","summary":"What a Swiss household pays as employer: wage, holiday pay, contributions and net, by canton.","description":"Calculates what a household in Switzerland pays as the employer of a Helper for one month: wage, holiday pay and the public holiday share each with its percentage, employer and Helper contributions, accident cover where a published rate applies, the Helper's net pay and the binding minimum wage, with the rates date, assumptions and an official source per line. Unknown or out of range inputs are refused by name. Personal fields (birth_date, reference_age_sex, employment_start, takeover, source_tax, accident) are accepted only in a POST body, used once and never stored. The same calculator is available to assistants as an MCP server at /mcp.","contact":{"name":"Helpore","email":"hello@helpore.com","url":"https://www.helpore.com"}},"servers":[{"url":"https://www.helpore.com"}],"paths":{"/tools/household-cost/v1":{"get":{"operationId":"estimateHouseholdEmployerCostGet","summary":"Estimate a household employer's month","description":"The estimate for the fields given in the query. Personal fields are refused here (use_post).","parameters":[{"name":"on_date","in":"query","required":false,"description":"The day the figures are for (YYYY-MM-DD, Europe/Zurich). Default: today. Refused outside a year the rate tables cover.","schema":{"type":"string","format":"date"}},{"name":"canton","in":"query","required":true,"description":"The canton where the work is done, as its two letter code (ZH, GE, TI and so on). Never defaulted.","schema":{"enum":["AG","AI","AR","BE","BL","BS","FR","GE","GL","GR","JU","LU","NE","NW","OW","SG","SH","SO","SZ","TG","TI","UR","VD","VS","ZG","ZH"]}},{"name":"postcode","in":"query","required":false,"description":"The postcode of the household; it must lie in the canton.","schema":{"type":"string","pattern":"^[1-9][0-9]{3}$"}},{"name":"wage_type","in":"query","required":true,"description":"hourly or monthly.","schema":{"enum":["hourly","monthly"]}},{"name":"hourly_base_rate_chf","in":"query","required":false,"description":"The hourly wage in CHF before holiday pay and the public holiday share (a decimal string such as \"30.00\" or a number).","schema":{"oneOf":[{"type":"string","pattern":"^\\d{1,5}(\\.\\d{1,2})?$"},{"type":"number","multipleOf":0.01}],"minimum":1,"maximum":200}},{"name":"hourly_rate_includes_holiday_pay","in":"query","required":false,"description":"True when the hourly wage given already carries holiday pay and the public holiday share; the base behind it is derived and returned.","schema":{"type":"boolean"}},{"name":"monthly_salary_chf","in":"query","required":false,"description":"The monthly salary in CHF (wage_type monthly). Refused where the hourly rate it comes to lies outside the hourly range.","schema":{"oneOf":[{"type":"string","pattern":"^\\d{1,5}(\\.\\d{1,2})?$"},{"type":"number","multipleOf":0.01}],"minimum":1,"maximum":99999.99}},{"name":"weekly_hours","in":"query","required":true,"description":"Hours worked a week, up to two decimals.","schema":{"oneOf":[{"type":"string","pattern":"^\\d{1,2}(\\.\\d{1,2})?$"},{"type":"number","multipleOf":0.01}],"minimum":1,"maximum":45}},{"name":"holiday_handling","in":"query","required":false,"description":"How holidays are paid. Hourly default: holiday pay in the hourly wage, as its own line. A monthly salary: paid time off only.","schema":{"enum":["holiday_pay_in_hourly_wage","paid_time_off"]}},{"name":"holiday_weeks","in":"query","required":false,"description":"Holiday weeks a year agreed. Default and minimum: what the canton, age and service owe.","schema":{"enum":[4,5,6]}},{"name":"qualification","in":"query","required":false,"description":"The Helper's qualification rung of the federal standard contract for household work. Default: unskilled.","schema":{"enum":["unskilled","unskilled_four_years_experience","skilled_eba_two_year_training","skilled_efz_three_year_training"]}},{"name":"thirteenth_month","in":"query","required":false,"description":"none, agreed or excluded (excluded only where the canton owes it). Default: the canton's rule.","schema":{"enum":["none","agreed","excluded"]}},{"name":"thirteenth_month_payment","in":"query","required":false,"description":"december or monthly. Default: december.","schema":{"enum":["december","monthly"]}},{"name":"procedure","in":"query","required":false,"description":"auto (from the two ceilings), simplified or ordinary. Default: auto.","schema":{"enum":["auto","simplified","ordinary"]}},{"name":"household_other_wages_annual_chf","in":"query","required":false,"description":"The household's other household wages a year in CHF, for the household ceiling. Default: 0.","schema":{"oneOf":[{"type":"string","pattern":"^\\d{1,5}(\\.\\d{1,2})?$"},{"type":"number","multipleOf":0.01}],"minimum":0,"maximum":99999.99}},{"name":"plan","in":"query","required":false,"description":"A Helpore plan, shown as its own fee line and never inside the employer cost. Default: none.","schema":{"enum":["none","admin_light","admin","admin_further"]}},{"name":"fee_payment_way","in":"query","required":false,"description":"How the plan fee is paid: qr_bill (the stated price) or card. Default: qr_bill.","schema":{"enum":["qr_bill","card"]}},{"name":"locale","in":"query","required":false,"description":"The language of the summary and the assumptions. Numbers are identical in every language. Default: en.","schema":{"enum":["en","de","fr","it","es","pt"]}}],"responses":{"200":{"description":"The month, line by line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"}}}},"400":{"description":"Refused: each field named with what it accepts (the value sent is never repeated), or caller_unknown.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Refusals"},{"$ref":"#/components/schemas/Error"}]}}}},"414":{"description":"The address is longer than the endpoint accepts; send a POST body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refusals"}}}},"421":{"description":"Not the endpoint's own host.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls from this caller; retry after the given seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The calculation could not be completed; a fixed code, never a message.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not available right now.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"estimateHouseholdEmployerCost","summary":"Estimate a household employer's month","description":"The estimate for the fields in the JSON body, the personal ones included.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"on_date":{"description":"The day the figures are for (YYYY-MM-DD, Europe/Zurich). Default: today. Refused outside a year the rate tables cover.","type":"string","format":"date"},"canton":{"description":"The canton where the work is done, as its two letter code (ZH, GE, TI and so on). Never defaulted.","enum":["AG","AI","AR","BE","BL","BS","FR","GE","GL","GR","JU","LU","NE","NW","OW","SG","SH","SO","SZ","TG","TI","UR","VD","VS","ZG","ZH"]},"postcode":{"description":"The postcode of the household; it must lie in the canton.","type":"string","pattern":"^[1-9][0-9]{3}$"},"wage_type":{"description":"hourly or monthly.","enum":["hourly","monthly"]},"hourly_base_rate_chf":{"description":"The hourly wage in CHF before holiday pay and the public holiday share (a decimal string such as \"30.00\" or a number).","oneOf":[{"type":"string","pattern":"^\\d{1,5}(\\.\\d{1,2})?$"},{"type":"number","multipleOf":0.01}],"minimum":1,"maximum":200},"hourly_rate_includes_holiday_pay":{"description":"True when the hourly wage given already carries holiday pay and the public holiday share; the base behind it is derived and returned.","type":"boolean"},"monthly_salary_chf":{"description":"The monthly salary in CHF (wage_type monthly). Refused where the hourly rate it comes to lies outside the hourly range.","oneOf":[{"type":"string","pattern":"^\\d{1,5}(\\.\\d{1,2})?$"},{"type":"number","multipleOf":0.01}],"minimum":1,"maximum":99999.99},"weekly_hours":{"description":"Hours worked a week, up to two decimals.","oneOf":[{"type":"string","pattern":"^\\d{1,2}(\\.\\d{1,2})?$"},{"type":"number","multipleOf":0.01}],"minimum":1,"maximum":45},"holiday_handling":{"description":"How holidays are paid. Hourly default: holiday pay in the hourly wage, as its own line. A monthly salary: paid time off only.","enum":["holiday_pay_in_hourly_wage","paid_time_off"]},"holiday_weeks":{"description":"Holiday weeks a year agreed. Default and minimum: what the canton, age and service owe.","enum":[4,5,6]},"birth_date":{"description":"The Helper's birth date (age rules, pension, holiday steps). Used once and never stored.","type":"string","format":"date"},"reference_age_sex":{"description":"Read only for birth years 1960 to 1963 (the reference age steps).","enum":["female","other"]},"employment_start":{"description":"The first working day. Default: 1 January of the on_date year.","type":"string","format":"date"},"qualification":{"description":"The Helper's qualification rung of the federal standard contract for household work. Default: unskilled.","enum":["unskilled","unskilled_four_years_experience","skilled_eba_two_year_training","skilled_efz_three_year_training"]},"thirteenth_month":{"description":"none, agreed or excluded (excluded only where the canton owes it). Default: the canton's rule.","enum":["none","agreed","excluded"]},"thirteenth_month_payment":{"description":"december or monthly. Default: december.","enum":["december","monthly"]},"procedure":{"description":"auto (from the two ceilings), simplified or ordinary. Default: auto.","enum":["auto","simplified","ordinary"]},"household_other_wages_annual_chf":{"description":"The household's other household wages a year in CHF, for the household ceiling. Default: 0.","oneOf":[{"type":"string","pattern":"^\\d{1,5}(\\.\\d{1,2})?$"},{"type":"number","multipleOf":0.01}],"minimum":0,"maximum":99999.99},"takeover":{"description":"The employment ran before this year's first month with another administration.","type":"object","properties":{"prior_start":{"description":"The day the Helper first started working for this household.","type":"string","format":"date"},"gross_ytd_chf":{"description":"Gross paid this year before the on_date month.","oneOf":[{"type":"string","pattern":"^\\d{1,5}(\\.\\d{1,2})?$"},{"type":"number","multipleOf":0.01}],"minimum":0,"maximum":99999.99},"holiday_days_taken":{"description":"Holiday days taken this year.","type":"integer","minimum":0,"maximum":60}},"required":[],"additionalProperties":false},"source_tax":{"description":"Source tax: a status, the plain answers the tariff is derived from, or the raw tariff code. Used once and never stored.","type":"object","properties":{"status":{"description":"Whether the Helper is taxed at source. Default: unknown (the answers below decide).","enum":["unknown","not_liable","liable"]},"tariff_code":{"description":"The ESTV tariff code, if known. Never shown back.","type":"string","pattern":"^[A-Z][0-9][NY]$"},"tax_canton":{"description":"The canton whose ESTV tariff applies. Default: the canton of the work.","enum":["AG","AI","AR","BE","BL","BS","FR","GE","GL","GR","JU","LU","NE","NW","OW","SG","SH","SO","SZ","TG","TI","UR","VD","VS","ZG","ZH"]},"residence":{"description":"Where the Helper lives.","enum":["switzerland","germanyDaily","germanyNotDaily","italyBorder","elsewhere"]},"swiss_or_c_permit":{"description":"The Helper is Swiss or holds a C permit.","type":"boolean"},"married_living_together":{"description":"Married or in a registered partnership and living together (separated counts as no).","type":"boolean"},"spouse_swiss_or_c_permit":{"description":"The spouse is Swiss or holds a C permit.","type":"boolean"},"spouse_has_earnings":{"description":"The spouse has earnings or income replacing a wage.","type":"boolean"},"children":{"description":"Children under 18 or in their first education the Helper (or the couple) mainly keeps.","type":"integer","minimum":0,"maximum":9},"children_live_with_helper":{"description":"The children live with the Helper.","type":"boolean"},"lives_with_other_parent":{"description":"The Helper lives with the children's other parent.","type":"boolean"},"earns_more_than_other_parent":{"description":"In that household the Helper earns more than the other parent.","type":"boolean"},"church_member":{"description":"Member of the Roman Catholic, Reformed or Christian Catholic church.","type":"boolean"},"italy_started_before_cutoff":{"description":"Living in the Italian border zone: started working there before the 2020 agreement's cut off.","type":"boolean"}},"required":[],"additionalProperties":false},"accident":{"description":"How the compulsory accident cover is settled.","type":"object","properties":{"route":{"description":"auto (the compensation office where it offers cover, else an insurer), office or insurer. Default: auto.","enum":["auto","office","insurer"]}},"required":[],"additionalProperties":false},"plan":{"description":"A Helpore plan, shown as its own fee line and never inside the employer cost. Default: none.","enum":["none","admin_light","admin","admin_further"]},"fee_payment_way":{"description":"How the plan fee is paid: qr_bill (the stated price) or card. Default: qr_bill.","enum":["qr_bill","card"]},"locale":{"description":"The language of the summary and the assumptions. Numbers are identical in every language. Default: en.","enum":["en","de","fr","it","es","pt"]}},"required":["canton","wage_type","weekly_hours"],"additionalProperties":false}}}},"responses":{"200":{"description":"The month, line by line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"}}}},"400":{"description":"Refused: each field named with what it accepts (the value sent is never repeated), or caller_unknown.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Refusals"},{"$ref":"#/components/schemas/Error"}]}}}},"413":{"description":"The body is larger than the endpoint accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refusals"}}}},"415":{"description":"The body must be application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refusals"}}}},"421":{"description":"Not the endpoint's own host.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls from this caller; retry after the given seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The calculation could not be completed; a fixed code, never a message.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not available right now.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Money":{"type":"object","required":["chf","rappen"],"properties":{"chf":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Swiss francs as a decimal string."},"rappen":{"type":"integer","description":"The same amount in integer rappen."}}},"Refusals":{"type":"object","required":["error","refusals"],"properties":{"error":{"const":"invalid_input"},"refusals":{"type":"array","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"enum":["unknown_field","duplicate_parameter","missing_field","invalid_type","invalid_format","out_of_range","unknown_value","use_post","not_applicable","too_deep","invalid_json","body_too_large","url_too_long","unsupported_content_type"]},"message":{"type":"string"},"allowed":{"type":"array"},"min":{"type":"number"},"max":{"type":"number"}}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Estimate":{"type":"object","description":"meta (api_version, payroll_rules, on_date, tables with read_on and source, fingerprint), inputs (the normalised echo without personal fields), derived, wage_lines (1000, 1025, 1020, 1040), gross, helper_deductions, employer_contributions, insurance, helper_net (exact or before_open_parts), employer_cost (statutory, with_accident), plan_fees, annual, floor, source_tax, summary, assumptions, sources, must_not_claim. Every amount is a Money object.","required":["meta","wage_lines","gross","employer_cost","helper_net","summary","assumptions","sources"],"properties":{"meta":{"type":"object","required":["api_version","payroll_rules","on_date","tables","fingerprint"],"properties":{"api_version":{"const":"1.0.0"},"payroll_rules":{"type":"string"},"on_date":{"type":"string","format":"date"},"tables":{"type":"array"},"fingerprint":{"type":"string"}}},"gross":{"$ref":"#/components/schemas/Money"},"employer_cost":{"type":"object","properties":{"statutory":{"$ref":"#/components/schemas/Money"},"with_accident":{"oneOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]},"per_hour_chf":{"type":["string","null"]}}},"summary":{"type":"string"},"assumptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}}}}}}}}}