Appearance
Yearly numbers
Many payroll figures change every year: contribution percentages, income limits, and the tax-free allowances that the Finnish Tax Administration (Verohallinto) sets for travel expenses. One anonymous endpoint returns them for a given date, so your system does not need to keep its own copy. Examples use the test environment; see Environments for demo and production.
The endpoint
| Method | Path | Purpose |
|---|---|---|
GET | /v03/api/calculator/yearlyNumbers/{forDate} | All yearly changing numbers for the year of forDate |
GET | /v03/api/calculator/yearlyHolidays/{forDate} | Only the holidays of the year |
The same two endpoints exist in v04 under /v04/. See Versions and changes.
http
GET https://test-secure.salaxy.com/v03/api/calculator/yearlyNumbers/2026-09-28- No authentication. You can call it without an access token.
forDateselects the year. Give an ISO 8601 date, for example2026-09-28. The year of that date decides the numbers.- A year that is not published yet returns
404. The numbers of the next year become available when they are set, usually in December. Branch on the status, not on the message; see Errors. - Do not trust the API reference description of the window. It says the endpoint supports two years. In practice it serves every year from 2014 up to the latest published year, and
404for any other.
The response
| Property | Content |
|---|---|
year | The year that the numbers apply to |
sideCosts | Contribution percentages, income limits, the domestic tax-free allowances, meal benefit and meal ticket values, household deduction rates and the protected portion of foreclosure |
taxFreeNumbers | Tax-free mileage allowances per vehicle type and international daily allowances per country |
holidays | The Finnish public holidays of the year |
The names of the fields are in the YearlyChangingNumbers and YearlySideCosts models of the OpenAPI document. Read the figures from the response; do not copy them from a document, because they change every year.
Units
All amounts are in euros.
| Where | Unit |
|---|---|
sideCosts.taxFreeKmAllowance | Euros per kilometre |
sideCosts.taxFreeDailyAllowance, taxFreeDailyHalfAllowance | Euros per day, domestic full and partial day |
taxFreeNumbers.mileage.* | Euros per kilometre |
taxFreeNumbers.countries.* | Euros per day |
sideCosts.taxFreeKmAllowance and taxFreeNumbers.mileage.car hold the same base car rate.
Mileage allowances
taxFreeNumbers.mileage holds the tax-free kilometre allowance (kilometrikorvaus) per vehicle type, with the surcharges allowed on top of the base rate.
| Field | Meaning |
|---|---|
car | Base rate for the employee's own car |
carLimitedBenefit | Rate for a car with a limited car benefit (käyttöetuauto) when the employee pays the fuel or electricity |
passenger | Surcharge for each extra person who travels in the car |
carAdditions.trailer, caravan, canteen, largeMachinery, dogInTheCar, constructionSite | Surcharges for a trailer, a caravan, a towed break hut, heavy or large machinery, a dog in the car, and forest roads or construction sites closed to other traffic |
other.* | Base rates for other vehicles: motorboats, snowmobile, quad bike, motorcycle, moped and other transport |
- Surcharges.
carAdditionsapplies tocaronly.passengerapplies tocarand to the vehicles inother, but not tocarLimitedBenefit. Add each surcharge that applies to the trip to the base rate. - Send the full price on a
milageOwnCarrow. The server does not price this row: it keeps thepriceyou send. Compute the base rate plus the surcharges yourself. - The keys are identifiers. A
milageOwnCarrow stores them:data.vehicleTypeholds a key ofother(orcar,carLimitedBenefit,custom) anddata.additionsholds keys ofcarAdditions. Write them exactly as the API returns them. - Older rows may carry earlier spellings. Rows saved before the keys were corrected can contain
docInTheCar(nowdogInTheCar),contstructionSite(nowconstructionSite) orsnowMobile(nowsnowmobile). If your system reads saved rows, accept both spellings.
International daily allowances
taxFreeNumbers.countries holds the tax-free daily allowance (ulkomaan päiväraha) for work trips abroad. The key is the country or region in English with a capital letter, for example Sweden or UnitedStates. The value is the full daily allowance in euros.
- The key is an identifier. A daily allowance row stores it in
data.country. Write it exactly as the API returns it. - Finland is not in the list. The domestic allowances are
taxFreeDailyAllowanceandtaxFreeDailyHalfAllowanceinsideCosts. - The key
Othercovers the countries that are not listed.
Years that are covered
Date in forDate | sideCosts | taxFreeNumbers |
|---|---|---|
| 2022 or later, up to the latest published year | That year's numbers | That year's numbers |
| Before 2022 | That year's numbers | The latest year's numbers. Do not use them |
| A year that is not published yet | 404 | 404 |
Old years can hold 0 in fields that were not recorded. A 0 in an early year means "not recorded", not "zero".
Test it
Call the endpoint without a token for a date in the current year, then for a date a few years ahead and check that you get 404. Then create a row that uses the numbers: see Salary calculations.
Checklist
- You read the figures from the API (or cache them for the year) and do not copy them into your code.
- You branch on
404for a year that is not published. - Keys such as
SwedenanddogInTheCarare written exactly as returned. - A
milageOwnCarrow carries the full price, base rate plus surcharges. - You do not use
taxFreeNumbersfor a date before 2022.

