# 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](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Your 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. (One anonymous call returns the year's numbers in three parts.)*

## 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](https://code.salaxy.com/reference/versions.md).

```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](https://code.salaxy.com/reference/errors.md).
- **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

| 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](https://code.salaxy.com/reference/rest-api.md). 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.** `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 `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](https://code.salaxy.com/integration/calculations.md).

## 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.
