Skip to content

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.

Reading the yearly numbersYour system calls one anonymous endpoint with a date, with no token. The Salaxy API answers with the numbers of that date's year in three parts: side costs such as contribution percentages and domestic tax-free allowances, tax-free numbers such as mileage rates and international daily allowances, and the public holidays of the year. A year that is not published yet returns 404.YOUR SYSTEMGET with a dateANSWER FOR THAT YEARsideCostscontribution percentages, limits, domestic allowancestaxFreeNumbersmileage rates, international daily allowancesholidayspublic holidays of the yearno token
One anonymous call returns the year's numbers in three parts.

The endpoint ​

MethodPathPurpose
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.
  • forDate selects the year. Give an ISO 8601 date, for example 2026-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 404 for any other.

The response ​

PropertyContent
yearThe year that the numbers apply to
sideCostsContribution percentages, income limits, the domestic tax-free allowances, meal benefit and meal ticket values, household deduction rates and the protected portion of foreclosure
taxFreeNumbersTax-free mileage allowances per vehicle type and international daily allowances per country
holidaysThe 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.

WhereUnit
sideCosts.taxFreeKmAllowanceEuros per kilometre
sideCosts.taxFreeDailyAllowance, taxFreeDailyHalfAllowanceEuros 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.

FieldMeaning
carBase rate for the employee's own car
carLimitedBenefitRate for a car with a limited car benefit (käyttöetuauto) when the employee pays the fuel or electricity
passengerSurcharge for each extra person who travels in the car
carAdditions.trailer, caravan, canteen, largeMachinery, dogInTheCar, constructionSiteSurcharges 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. carAdditions applies to car only. passenger applies to car and to the vehicles in other, but not to carLimitedBenefit. Add each surcharge that applies to the trip to the base rate.
  • Send the full price on a milageOwnCar row. The server does not price this row: it keeps the price you send. Compute the base rate plus the surcharges yourself.
  • The keys are identifiers. A milageOwnCar row stores them: data.vehicleType holds a key of other (or car, carLimitedBenefit, custom) and data.additions holds keys of carAdditions. Write them exactly as the API returns them.
  • Older rows may carry earlier spellings. Rows saved before the keys were corrected can contain docInTheCar (now dogInTheCar), contstructionSite (now constructionSite) or snowMobile (now snowmobile). 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 taxFreeDailyAllowance and taxFreeDailyHalfAllowance in sideCosts.
  • The key Other covers the countries that are not listed.

Years that are covered ​

Date in forDatesideCoststaxFreeNumbers
2022 or later, up to the latest published yearThat year's numbersThat year's numbers
Before 2022That year's numbersThe latest year's numbers. Do not use them
A year that is not published yet404404

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 404 for a year that is not published.
  • Keys such as Sweden and dogInTheCar are written exactly as returned.
  • A milageOwnCar row carries the full price, base rate plus surcharges.
  • You do not use taxFreeNumbers for a date before 2022.

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.