{"openapi":"3.0.3","info":{"title":"Japan Payroll and Labor Constants","description":"Japanese payroll data is public but scattered across 47 per-prefecture spreadsheets, ministry PDFs that change every April, and a separate minimum wage site that changes every October.\n\nThis API packages it. Premiums are computed on the standard monthly remuneration (a 50-grade step function) rather than actual salary — except employment insurance, which uses actual salary. Pension caps at grade 32. Long-term care applies only to ages 40-64. The employee share rounds half down. Getting any one of these wrong produces numbers that look plausible and are wrong.\n\nThe same treatment is applied to the rest of Japanese statutory reference data. Public holidays come from the Cabinet Office and include substitute holidays, citizens' holidays and one-off imperial events, so business-day arithmetic is correct in the awkward years rather than only the tidy ones. Consumption tax covers every rate since 1989 with the national and local split. Corporate numbers are validated with the National Tax Agency check digit algorithm, which is the identifier behind Peppol scheme ICD 0188.\n\nEvery answer names the statute or notice it rests on, and `?include=statute_text` attaches the full text of those provisions to any response - so the rule, the figure and the words of the Act arrive together instead of a trip to e-Gov.\n\nBeyond the raw figures, the API answers the questions payroll actually asks: whether a pay change forces a standard remuneration revision, which months a maternity or childcare leave exempts from premiums, whether a leaving employee owes a final month of insurance. Several of those rules live in ministerial notices rather than in the Acts - the two-grade test for 随時改定 appears nowhere in 健康保険法 - so every answer names the notice or statute it came from, and says which requirement failed when the answer is no.\n\nAll figures are extracted programmatically from the official government sources and verified against the values published in them: the test suite checks over 3,000 assertions against the published premium and withholding tables, cell by cell. Licensing differs by publisher - 厚生労働省 and 国税庁 material is under the Japan Public Data License v1.0, while 全国健康保険協会 permits reproduction with attribution but not modification - so each response carries the terms for the source it drew on. This service is not endorsed by any government agency.","version":"2.9.0","license":{"name":"Mixed: Japan Public Data License v1.0 (公共データ利用規約 第1.0版), except 全国健康保険協会 data - see the attribution block in each response","url":"https://www.digital.go.jp/resources/open_data/public_data_license_v1.0"}},"servers":[{"url":"https://japan-payroll-api.tsumugi.workers.dev"}],"security":[],"paths":{"/":{"get":{"summary":"API information","description":"Endpoint list, data sources and attribution.","operationId":"getRoot","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"tags":["Meta"]}},"/v1/prefectures":{"get":{"summary":"List all 47 prefectures","description":"English name, Japanese name and JIS code for each prefecture.","operationId":"getV1Prefectures","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"tags":["Reference"]}},"/v1/insurance-rates":{"get":{"summary":"Social insurance rates for a prefecture","description":"Health insurance, long-term care, pension and child-support rates, plus bonus caps and the employer-only child-care contribution rate.","operationId":"getV1InsuranceRates","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"prefecture","in":"query","required":true,"description":"English name (Tokyo), Japanese (東京 / 東京都), or JIS code 1-47.","schema":{"type":"string","example":"Tokyo"}}],"tags":["Rates"]}},"/v1/standard-remuneration":{"get":{"summary":"Standard remuneration grade for an amount","description":"Maps a monthly amount in yen to its health grade (1-50) and pension grade (1-32), including whether the pension grade was clamped.","operationId":"getV1StandardRemuneration","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"remuneration","in":"query","required":true,"description":"Monthly remuneration in yen.","schema":{"type":"integer","example":350000}}],"tags":["Rates"]}},"/v1/standard-remuneration/table":{"get":{"summary":"Full standard remuneration table","description":"All 50 health grades and 32 pension grades with their yen bands.","operationId":"getV1StandardRemunerationTable","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"tags":["Rates"]}},"/v1/employment-insurance":{"get":{"summary":"Employment insurance rates by business type","description":"Employee and employer shares, with the statutory breakdown.","operationId":"getV1EmploymentInsurance","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"business_type","in":"query","required":false,"description":"Business category. Defaults to general.","schema":{"type":"string","enum":["general","agriculture_forestry_fishery_sake","construction"],"example":"general"}}],"tags":["Rates"]}},"/v1/minimum-wage":{"get":{"summary":"Minimum wage in effect on a date","description":"Hourly minimum wage for a prefecture. Without a date, returns the rate currently in force.","operationId":"getV1MinimumWage","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"prefecture","in":"query","required":true,"description":"English name, Japanese, or JIS code 1-47.","schema":{"type":"string","example":"Tokyo"}},{"name":"date","in":"query","required":false,"description":"ISO date (YYYY-MM-DD). Returns the rate in force on that day.","schema":{"type":"string","example":"2020-01-01"}}],"tags":["Minimum wage"]}},"/v1/minimum-wage/history":{"get":{"summary":"Minimum wage history since FY2002","description":"24 fiscal years of revisions with their effective dates.","operationId":"getV1MinimumWageHistory","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"prefecture","in":"query","required":true,"description":"English name, Japanese, or JIS code 1-47.","schema":{"type":"string","example":"Tokyo"}}],"tags":["Minimum wage"]}},"/v1/payroll":{"get":{"summary":"Full monthly payslip in one call","description":"Resolves the standard remuneration grade, applies every statutory premium with the correct rounding, splits each into employee and employer shares, then withholds income tax and returns net pay.\n\nIncome tax is charged on pay after social insurance, not on gross pay. This endpoint derives that base itself, which is the step callers most often get wrong. Resident tax is assessed by the municipality and cannot be computed here, but a figure you supply will be subtracted.","operationId":"getV1Payroll","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"prefecture","in":"query","required":true,"description":"English name, Japanese, or JIS code 1-47.","schema":{"type":"string","example":"Tokyo"}},{"name":"monthly_salary","in":"query","required":true,"description":"Actual monthly salary in yen.","schema":{"type":"integer","example":350000}},{"name":"age","in":"query","required":false,"description":"Age. Long-term care insurance applies from 40 to 64.","schema":{"type":"integer","example":40}},{"name":"business_type","in":"query","required":false,"description":"Business category for employment insurance.","schema":{"type":"string","enum":["general","agriculture_forestry_fishery_sake","construction"],"example":"general"}},{"name":"column","in":"query","required":false,"description":"Withholding column. 甲 if a 扶養控除等申告書 was filed.","schema":{"type":"string","enum":["kou","otsu"],"example":"kou"}},{"name":"dependants","in":"query","required":false,"description":"扶養親族等の数, for the income tax step.","schema":{"type":"integer","example":2}},{"name":"income_tax","in":"query","required":false,"description":"Include withholding income tax. Defaults to true.","schema":{"type":"string","example":"true"}},{"name":"resident_tax","in":"query","required":false,"description":"Resident tax to subtract. Assessed by the municipality; not computed here.","schema":{"type":"integer","example":15000}}],"tags":["Payroll"]}},"/v1/enums":{"get":{"summary":"Every accepted enum value and error code","description":"The closed sets this API accepts, so they can be read at build time rather than discovered from a 400.","operationId":"getV1Enums","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"tags":["Meta"]}},"/v1/holidays":{"get":{"summary":"Public holidays for a year or date range","description":"Japanese public holidays as published by the Cabinet Office, 1955-2027. Includes substitute holidays and citizens' holidays, plus one-off imperial events such as the 2019 enthronement days.","operationId":"getV1Holidays","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"year","in":"query","required":false,"description":"Calendar year. Omit if using from/to.","schema":{"type":"integer","example":2026}},{"name":"from","in":"query","required":false,"description":"Range start (ISO date).","schema":{"type":"string","example":"2026-01-01"}},{"name":"to","in":"query","required":false,"description":"Range end (ISO date).","schema":{"type":"string","example":"2026-12-31"}}],"tags":["Calendar"]}},"/v1/holidays/check":{"get":{"summary":"Is a date a holiday, weekend or business day","description":"Returns the weekday plus holiday, weekend and business-day flags.","operationId":"getV1HolidaysCheck","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"calendar","in":"query","required":false,"description":"bank adds the 12/31-1/3 closure required by 銀行法施行令第5条.","schema":{"type":"string","enum":["standard","bank"],"example":"standard"}},{"name":"date","in":"query","required":true,"description":"ISO date (YYYY-MM-DD).","schema":{"type":"string","example":"2026-01-01"}}],"tags":["Calendar"]}},"/v1/business-days":{"get":{"summary":"Count business days in a range","description":"Counts business days, weekends and holidays between two dates inclusive. A business day is a weekday that is not a public holiday.","operationId":"getV1BusinessDays","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"calendar","in":"query","required":false,"description":"bank adds the 12/31-1/3 closure required by 銀行法施行令第5条.","schema":{"type":"string","enum":["standard","bank"],"example":"standard"}},{"name":"from","in":"query","required":true,"description":"Range start (ISO date).","schema":{"type":"string","example":"2026-01-01"}},{"name":"to","in":"query","required":true,"description":"Range end (ISO date).","schema":{"type":"string","example":"2026-03-31"}}],"tags":["Calendar"]}},"/v1/business-days/shift":{"get":{"summary":"Move N business days forward or back","description":"Settlement-date arithmetic: skips weekends and public holidays. Negative values move backwards.","operationId":"getV1BusinessDaysShift","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"calendar","in":"query","required":false,"description":"bank adds the 12/31-1/3 closure required by 銀行法施行令第5条.","schema":{"type":"string","enum":["standard","bank"],"example":"standard"}},{"name":"date","in":"query","required":true,"description":"Starting ISO date.","schema":{"type":"string","example":"2026-01-01"}},{"name":"days","in":"query","required":false,"description":"Business days to move. 1 = next business day, -1 = previous.","schema":{"type":"integer","example":1}}],"tags":["Calendar"]}},"/v1/consumption-tax":{"get":{"summary":"Consumption tax rate in force on a date","description":"Standard and reduced consumption tax rates with the national/local split. Optionally applies the rate to an amount, truncating the tax to the yen as invoices do.","operationId":"getV1ConsumptionTax","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"date","in":"query","required":false,"description":"ISO date. Omit for the rate currently in force.","schema":{"type":"string","example":"2015-01-01"}},{"name":"amount","in":"query","required":false,"description":"Tax-exclusive amount in yen to apply the rate to.","schema":{"type":"integer","example":1000}},{"name":"reduced","in":"query","required":false,"description":"Use the reduced rate (food, drink and qualifying newspapers).","schema":{"type":"string","example":"true"}}],"tags":["Tax"]}},"/v1/consumption-tax/history":{"get":{"summary":"Every consumption tax change since 1989","description":"All four rate periods with effective dates and national/local splits.","operationId":"getV1ConsumptionTaxHistory","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"tags":["Tax"]}},"/v1/corporate-number/validate":{"get":{"summary":"Validate a corporate number (法人番号) check digit","description":"Structural validation of a 13-digit Japanese Corporate Number using the National Tax Agency check-digit algorithm. This is the identifier behind Peppol participant scheme ICD 0188. Hyphens and spaces are ignored. Confirms the number is well-formed, not that the corporation exists.","operationId":"getV1CorporateNumberValidate","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"number","in":"query","required":true,"description":"13-digit corporate number.","schema":{"type":"string","example":"8700110005901"}}],"tags":["Corporate number"]}},"/v1/corporate-number/check-digit":{"get":{"summary":"Compute the check digit for a 12-digit base number","description":"Turns a 12-digit 会社法人等番号 into the full 13-digit corporate number by computing its check digit.","operationId":"getV1CorporateNumberCheckDigit","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"base","in":"query","required":true,"description":"12-digit base number (会社法人等番号).","schema":{"type":"string","example":"700110005901"}}],"tags":["Corporate number"]}},"/v1/invoice-number/validate":{"get":{"summary":"Validate a qualified invoice registration number","description":"Structural check of a 適格請求書発行事業者 registration number (T + 13 digits). Reports the check digit separately from the format: a passing number may belong to a corporation or a sole proprietor, since both satisfy the same rule.","operationId":"getV1InvoiceNumberValidate","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"number","in":"query","required":true,"description":"Registration number, e.g. T8700110005901.","schema":{"type":"string","example":"T8700110005901"}}],"tags":["Corporate number"]}},"/v1/withholding-tax":{"get":{"summary":"Monthly withholding income tax","description":"源泉徴収税額表 月額表 for 令和8年分, including the reconstruction surtax. Covers the 231 published brackets, the anchor-and-rate rules above 740,000 yen, and the 1,610 yen deduction for each dependant beyond seven.","operationId":"getV1WithholdingTax","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"taxable_amount","in":"query","required":true,"description":"Monthly pay AFTER social insurance deductions, in yen.","schema":{"type":"integer","example":300000}},{"name":"column","in":"query","required":false,"description":"甲 if a 扶養控除等申告書 was filed, otherwise 乙.","schema":{"type":"string","enum":["kou","otsu"],"example":"kou"}},{"name":"dependants","in":"query","required":false,"description":"扶養親族等の数. Ignored for the 乙 column.","schema":{"type":"integer","example":2}}],"tags":["Withholding tax"]}},"/v1/withholding-tax/computer":{"get":{"summary":"Monthly withholding tax by the formula method","description":"電算機計算の特例 — the Ministry of Finance formula that payroll software may use instead of the table. 甲 column only, from 令和8年分. Returns each deduction so the arithmetic is auditable. Results differ slightly from the table by design; the difference is settled at the year-end adjustment.","operationId":"getV1WithholdingTaxComputer","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"taxable_amount","in":"query","required":true,"description":"Monthly pay AFTER social insurance deductions, in yen.","schema":{"type":"integer","example":400000}},{"name":"spouse","in":"query","required":false,"description":"Whether a 源泉控除対象配偶者 applies.","schema":{"type":"string","example":"false"}},{"name":"dependants","in":"query","required":false,"description":"源泉控除対象親族の数.","schema":{"type":"integer","example":2}}],"tags":["Withholding tax"]}},"/v1/withholding-tax/daily":{"get":{"summary":"Daily withholding income tax (日額表)","description":"The daily table, used for day labourers and short engagements. The 丙 column is the one that applies to work engaged by the day, and it has no dependant adjustment — passing dependants with it is an error rather than a silently ignored parameter.","operationId":"getV1WithholdingTaxDaily","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"taxable_amount","in":"query","required":true,"description":"Daily pay after social insurance, in yen.","schema":{"type":"integer","example":12000}},{"name":"column","in":"query","required":false,"description":"甲 (declaration filed), 乙 (not filed), 丙 (engaged by the day).","schema":{"type":"string","enum":["kou","otsu","hei"],"example":"hei"}},{"name":"dependants","in":"query","required":false,"description":"源泉控除対象親族の数. Only meaningful for the 甲 column.","schema":{"type":"integer","example":2}}],"tags":["Tax"]}},"/v1/bonus-tax":{"get":{"summary":"Withholding income tax on a bonus","description":"Bonuses are taxed on a rate derived from the previous month's pay, not from the bonus itself (賞与に対する源泉徴収税額の算出率の表). Two statutory exceptions apply when the bonus exceeds ten times the previous month's pay, or when there was no pay in the previous month; both are detected and reported rather than silently mis-taxed.","operationId":"getV1BonusTax","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"bonus","in":"query","required":true,"description":"Gross bonus in yen.","schema":{"type":"integer","example":500000}},{"name":"previous_month_pay","in":"query","required":true,"description":"Gross pay in the month before the bonus.","schema":{"type":"integer","example":350000}},{"name":"previous_month_insurance","in":"query","required":false,"description":"Social insurance deducted from that pay.","schema":{"type":"integer","example":55750}},{"name":"bonus_insurance","in":"query","required":true,"description":"Social insurance deducted from THIS bonus. The tax is charged on the bonus after it (所得税法第186条第2項), so leaving it out overstates the tax by roughly 3,000 yen on a 500,000 yen bonus. GET /v1/bonus-insurance computes the figure.","schema":{"type":"integer","example":75000}},{"name":"dependants","in":"query","required":false,"description":"源泉控除対象親族の数.","schema":{"type":"integer","example":2}},{"name":"column","in":"query","required":false,"description":"甲 or 乙 column.","schema":{"type":"string","enum":["kou","otsu"],"example":"kou"}}],"tags":["Tax"]}},"/v1/bonus-insurance":{"get":{"summary":"Social insurance on a bonus","description":"Premiums on 標準賞与額 — the bonus truncated to the thousand yen. The two caps behave differently and are routinely conflated: health, long-term care and child support cap at 5,730,000 yen per fiscal year cumulatively, while pension caps at 1,500,000 yen per payment. The annual cap depends on bonuses already paid, so pass fiscal_year_to_date or it cannot apply.","operationId":"getV1BonusInsurance","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"prefecture","in":"query","required":true,"description":"English name, Japanese, or JIS code 1-47.","schema":{"type":"string","example":"Tokyo"}},{"name":"bonus","in":"query","required":true,"description":"Gross bonus in yen.","schema":{"type":"integer","example":800000}},{"name":"fiscal_year_to_date","in":"query","required":false,"description":"標準賞与額 already counted since 1 April, for the annual cap.","schema":{"type":"integer","example":0}},{"name":"age","in":"query","required":false,"description":"Age, for long-term care. Prefer birth_date.","schema":{"type":"integer","example":40}},{"name":"birth_date","in":"query","required":false,"description":"Birth date. More accurate than age: coverage turns on the day before a birthday (年齢計算ニ関スル法律).","schema":{"type":"string","example":"1986-04-01"}},{"name":"as_of","in":"query","required":false,"description":"Date to judge age against. Defaults to today.","schema":{"type":"string","example":"2026-08-25"}}],"tags":["Payroll"]}},"/v1/payroll/batch":{"post":{"summary":"Up to 500 payslips in one call","description":"The same calculation as /v1/payroll, applied to a list of employees with shared defaults, plus run totals. Rows that fail validation come back as errors carrying their index and id; the rest still compute. Add ?detail=compact for payout figures only, roughly a tenth the response size.","operationId":"postV1PayrollBatch","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"detail","in":"query","required":false,"description":"compact returns payout figures only.","schema":{"type":"string","enum":["full","compact"],"example":"full"}}],"tags":["Payroll"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["employees"],"properties":{"defaults":{"type":"object","description":"Applied to any row that omits the field.","properties":{"prefecture":{"type":"string","example":"Tokyo"},"age":{"type":"integer","example":40},"business_type":{"type":"string","example":"general"},"column":{"type":"string","enum":["kou","otsu"]},"dependants":{"type":"integer","example":0},"income_tax":{"type":"boolean","example":true},"resident_tax":{"type":"integer","example":0}}},"employees":{"type":"array","maxItems":500,"items":{"type":"object","required":["monthly_salary"],"properties":{"id":{"type":"string","example":"emp-001"},"monthly_salary":{"type":"integer","example":350000},"prefecture":{"type":"string"},"age":{"type":"integer"},"business_type":{"type":"string"},"column":{"type":"string"},"dependants":{"type":"integer"},"income_tax":{"type":"boolean"},"resident_tax":{"type":"integer"}}}}}},"example":{"defaults":{"prefecture":"Tokyo","age":40,"dependants":0},"employees":[{"id":"emp-001","monthly_salary":350000,"dependants":2},{"id":"emp-002","monthly_salary":280000},{"id":"emp-003","monthly_salary":520000,"prefecture":"Osaka","age":66}]}}}}}},"/v1/standard-remuneration/revision":{"get":{"summary":"Is a 随時改定 (月額変更) due?","description":"Judges whether a pay change forces the standard remuneration to be revised, and answers separately for health insurance and pension — the two tables differ, so a change can move one and not the other, which is normal for higher earners because the pension table stops at grade 32.\n\nThree things must all hold: fixed pay actually changed, all three months reached the payment-basis-day threshold, and the grade moved far enough. None of that is in 健康保険法 — the two-grade test and the fixed-pay requirement both come from 昭和36年 保発第4号, and the notice's four single-grade exceptions at the top and bottom of each table are applied and named in the response. When it does not apply, the response says which requirement failed rather than returning a bare false.","operationId":"getV1StandardRemunerationRevision","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"current_remuneration","in":"query","required":true,"description":"The 報酬月額 the current grade was based on — not the 標準報酬月額. The upper and lower exceptions turn on actual pay.","schema":{"type":"integer","example":300000}},{"name":"months","in":"query","required":true,"description":"Three months as remuneration:payment_basis_days, from the month pay changed.","schema":{"type":"string","example":"350000:31,352000:30,349000:31"}},{"name":"fixed_pay_change","in":"query","required":true,"description":"Whether fixed pay rose, fell, or did not change. Overtime alone never triggers a revision.","schema":{"type":"string","enum":["increase","decrease","none"],"example":"increase"}},{"name":"worker_type","in":"query","required":false,"description":"Day threshold is 17, except 11 for 特定適用事業所の短時間労働者. The 15-day relaxation for パート applies to 定時決定 only.","schema":{"type":"string","enum":["general","part_time_short_hours","short_time_insured"],"example":"general"}}],"tags":["Standard remuneration"]}},"/v1/standard-remuneration/regular":{"get":{"summary":"Annual 定時決定 (算定基礎) from April-June pay","description":"The yearly redetermination effective each September. Months below the payment-basis-day threshold drop out of the average entirely rather than counting as zero. If no month qualifies the previous grade carries over by 保険者算定 — except for 短時間就労者, who have an intermediate step at 15 days that exists nowhere else in the scheme.","operationId":"getV1StandardRemunerationRegular","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"months","in":"query","required":true,"description":"April, May and June as remuneration:payment_basis_days.","schema":{"type":"string","example":"350000:30,352000:31,349000:30"}},{"name":"worker_type","in":"query","required":false,"description":"","schema":{"type":"string","enum":["general","part_time_short_hours","short_time_insured"],"example":"general"}},{"name":"previous_remuneration","in":"query","required":false,"description":"Used only to name the grade that carries over when no month qualifies.","schema":{"type":"integer","example":340000}},{"name":"acquired_month","in":"query","required":false,"description":"Month of enrolment, 1-12. Returns how long the 資格取得時決定 stays in force.","schema":{"type":"integer","example":3}}],"tags":["Standard remuneration"]}},"/v1/standard-remuneration/leave-end":{"get":{"summary":"Revision on returning from maternity or childcare leave","description":"A separate route with a lower bar than 随時改定: one grade of movement is enough, and fixed pay need not have changed at all — which matters because returning part-time usually cuts pay without changing any rate. Only one of the three months has to reach the day threshold, and the months that miss it are excluded from the average. The employee has to apply; an employer cannot file it alone. It is unavailable if another leave begins the day after this one ends.","operationId":"getV1StandardRemunerationLeaveEnd","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"kind","in":"query","required":true,"description":"産前産後休業終了時改定 or 育児休業等終了時改定.","schema":{"type":"string","enum":["maternity","childcare"],"example":"childcare"}},{"name":"current_remuneration","in":"query","required":true,"description":"報酬月額 before the leave.","schema":{"type":"integer","example":300000}},{"name":"months","in":"query","required":true,"description":"Three months from the one containing the day after the leave ended, as remuneration:payment_basis_days.","schema":{"type":"string","example":"260000:31,258000:30,262000:31"}},{"name":"worker_type","in":"query","required":false,"description":"","schema":{"type":"string","enum":["general","part_time_short_hours","short_time_insured"],"example":"general"}},{"name":"next_leave_starts_immediately","in":"query","required":false,"description":"True if another leave began the day after this one ended, which bars the application.","schema":{"type":"boolean","example":false}}],"tags":["Standard remuneration"]}},"/v1/standard-remuneration/annual-average":{"post":{"summary":"年間平均による保険者算定 for seasonal work","description":"For work whose April-June happens to be its busiest or quietest quarter, where the ordinary calculation would fix a grade that is wrong for eleven months of the year. Both routes exist: 定時決定 since April 2011, and 随時改定 since October 2018, the latter needing three separate grade tests to pass.\n\nThe 随時改定 figure is not a plain twelve-month average — it is the three-month average of fixed pay plus the twelve-month average of non-fixed pay, so the two are supplied separately. Both routes also require the employee's consent and that the swing recurs every year for reasons inherent to the work; neither is something an API can verify, so they are declared inputs and are reported back in the response.","operationId":"postV1StandardRemunerationAnnualAverage","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"tags":["Standard remuneration"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","months"],"properties":{"type":{"type":"string","enum":["regular","revision"],"description":"regular = 定時決定, revision = 随時改定."},"months":{"type":"array","minItems":12,"maxItems":12,"description":"For regular: 前年7月 to 当年6月. For revision: the 9 months before the pay change, then the 3 after it.","items":{"type":"object","required":["payment_basis_days"],"properties":{"month":{"type":"string","example":"2025-07"},"remuneration":{"type":"integer","description":"regular only: total pay."},"fixed":{"type":"integer","description":"revision only: fixed pay."},"non_fixed":{"type":"integer","description":"revision only: overtime etc."},"payment_basis_days":{"type":"integer","example":30}}}},"current_remuneration":{"type":"integer","example":270000,"description":"revision only."},"fixed_pay_change":{"type":"string","enum":["increase","decrease"],"description":"revision only."},"worker_type":{"type":"string","enum":["general","part_time_short_hours","short_time_insured"]},"recurring_annually":{"type":"boolean","example":true,"description":"The swing recurs every year for reasons inherent to the work."},"employee_consent":{"type":"boolean","example":true,"description":"The employee has consented. Mandatory."}}},"example":{"type":"regular","worker_type":"general","recurring_annually":true,"employee_consent":true,"months":[{"month":"2025-07","remuneration":250000,"payment_basis_days":31},{"month":"2025-08","remuneration":250000,"payment_basis_days":31},{"month":"2025-09","remuneration":250000,"payment_basis_days":30},{"month":"2025-10","remuneration":250000,"payment_basis_days":31},{"month":"2025-11","remuneration":250000,"payment_basis_days":30},{"month":"2025-12","remuneration":250000,"payment_basis_days":31},{"month":"2026-01","remuneration":250000,"payment_basis_days":31},{"month":"2026-02","remuneration":250000,"payment_basis_days":28},{"month":"2026-03","remuneration":250000,"payment_basis_days":31},{"month":"2026-04","remuneration":500000,"payment_basis_days":30},{"month":"2026-05","remuneration":500000,"payment_basis_days":31},{"month":"2026-06","remuneration":500000,"payment_basis_days":30}]}}}}}},"/v1/leave-exemption":{"get":{"summary":"Which months a maternity or childcare leave exempts","description":"Maternity and childcare leave look alike and are not. Maternity leave has no day-count test and exempts bonus premiums unconditionally; childcare leave gained a 14-day rule in October 2022 and exempts bonus premiums only when the leave exceeds one month. Two consequences catch implementations out: a leave ending mid-month exempts nothing by itself, and a single day of leave on the last day of a month is exempt. Employment insurance is never exempt — it is charged on wages actually paid.","operationId":"getV1LeaveExemption","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"kind","in":"query","required":false,"description":"産前産後休業 or 育児休業等.","schema":{"type":"string","enum":["maternity","childcare"],"example":"childcare"}},{"name":"start","in":"query","required":true,"description":"First day of leave.","schema":{"type":"string","example":"2026-03-15"}},{"name":"end","in":"query","required":true,"description":"Last day of leave.","schema":{"type":"string","example":"2026-03-28"}},{"name":"worked_days","in":"query","required":false,"description":"出生時育児休業 only: days worked during the leave, which come off the 14-day count.","schema":{"type":"integer","example":0}}],"tags":["Payroll"]}},"/v1/eligibility":{"get":{"summary":"Is social insurance due in a joining or leaving month?","description":"Coverage ends the day after the last day worked, not on it, so someone leaving on the last day of a month loses coverage in the next month and still owes that month's premium — while leaving one day earlier means no premium at all. This is the single most common payroll error at month end, and it moves a full month of premium.","operationId":"getV1Eligibility","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"month","in":"query","required":false,"description":"Month to judge, YYYY-MM or a full date. Defaults to today.","schema":{"type":"string","example":"2026-03"}},{"name":"joined_on","in":"query","required":false,"description":"First day of employment.","schema":{"type":"string","example":"2026-03-16"}},{"name":"left_on","in":"query","required":false,"description":"Last day worked.","schema":{"type":"string","example":"2026-03-30"}}],"tags":["Payroll"]}},"/v1/age-milestones":{"get":{"summary":"When 40, 65, 70 and 75 are reached, and what changes","description":"Under 年齢計算ニ関スル法律 an age is reached the day *before* the birthday, so someone born on the first of a month reaches it in the previous month and their premium changes a month earlier than a naive calculation suggests. Returns the exact date each threshold is crossed and which premium starts or stops: long-term care at 40 and 65, pension at 70, health insurance at 75.","operationId":"getV1AgeMilestones","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"birth_date","in":"query","required":true,"description":"Date of birth.","schema":{"type":"string","example":"1986-04-01"}},{"name":"as_of","in":"query","required":false,"description":"Date to judge against. Defaults to today.","schema":{"type":"string","example":"2026-08-25"}}],"tags":["Payroll"]}},"/v1/statute":{"get":{"summary":"Full text of a provision this API cites","description":"The judgement endpoints name the statute or notice their answer rests on. This returns its actual words, so a filing can be checked against the provision rather than against this API.\n\nCitations are written many ways in practice, and all of them resolve: abbreviations as practitioners use them (健保法43条, 厚年法81条の2, 徴収法11条), a missing 第, paragraph-level references (第43条第1項), and full-width digits. Only the provisions this API cites are bundled - roughly 28 across 8 laws. Anything else is refused rather than approximated.","operationId":"getV1Statute","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"parameters":[{"name":"ref","in":"query","required":true,"description":"A citation. See /v1/statute/index for everything available.","schema":{"type":"string","example":"健康保険法第43条"}}],"tags":["Statutes"]}},"/v1/statute/index":{"get":{"summary":"Every provision available, with its law","description":"Lists the provisions bundled and the laws they come from, with the law number and the date the version in force took effect.","operationId":"getV1StatuteIndex","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"tags":["Statutes"]}},"/v1/data-freshness":{"get":{"summary":"What each dataset covers and when it changes next","description":"Statutory figures change on fixed dates. This states the coverage and next expected revision of every dataset, so a stale figure is visible rather than silent.","operationId":"getV1DataFreshness","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or missing query parameter"}},"tags":["Meta"]}}}}