Skip to content

Tax cards ​

Salaxy withholds tax from each salary using the employee's tax card (verokortti). In nearly every case you let Salaxy fetch the card automatically; you set one by hand only when you must.

Examples use the test environment; see Environments for demo and production.

Where a tax card comes fromTwo sources feed the tax card that Salaxy keeps for an employee: the automatic card, which Salaxy fetches from the Tax Administration, and a manual card that you set through the REST API. The salary calculation uses the card to work out the withholding tax.Tax Administrationautomatic card (usual)Your systemmanual card (exception)Tax cardkept per employeeSalary calculationwithholding tax
Purple: Salaxy. The automatic card needs nothing from you except info.taxcard: "auto".

Which fits you? ​

Automatic card ​

Fits almost everyone: Salaxy fetches the card from the Tax Administration, and refreshes it.

Automatic card: how it works

Set info.taxcard to auto on the employment. Salaxy asks the Tax Administration for the card. You send nothing else.

MethodPathPurpose
POST/v03/api/taxcards/auto-setFetch and set the automatic card now. Query: personalId, taxPercentMinimum, salaryDate (default: today)
POST/v03/api/taxcards/auto-refreshCheck cards again. Query: taxcardIds, salaryDate, forceUpdate
GET/v03/api/taxcards/currentThe current cards of all non-terminated employments of the employer
GET/v03/api/taxcards/current/{paymentDate}The same for a payment date
GET/v03/api/taxcards/employment/{id}All current cards of one employment. Query: paymentDate
  • The income type is always salary for an automatic card at the moment.
  • A refresh is skipped if the card was checked within 2 days. forceUpdate=true skips that rule. If nothing changed, only the last-checked date is updated; if something changed, a new card is created.
  • Around the turn of the year, the current card may be the one for next year: in December and January current can return next year's card.
  • The worker can set a minimum percentage (taxPercentMinimum) that is withheld even when the card's percentage is lower.

Manual card ​

Fits when you hold the card yourself, for example a paper or PDF card, or a percentage the employer has agreed.

Manual card: how it works

Set info.taxcard to manual on the employment, then save a tax card for it.

MethodPathPurpose
GET/v03/api/taxcards/newA blank card to fill in
POST/v03/api/taxcardsCreate or update a card
GET/v03/api/taxcards/{id}Read one card
DELETE/v03/api/taxcards/{id}Delete a card
GET/v03/api/taxcardsFind cards. OData query; see Queries
http
POST /v03/api/taxcards HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "employmentId": "EMP123",
  "card": {
    "personalId": "190372-942M",
    "forYear": 2026,
    "kind": "defaultYearly",
    "taxPercent": 10,
    "incomeLimit": 10000,
    "taxPercent2": 40,
    "validity": { "start": "2026-01-01", "end": "2026-12-31" }
  }
}
FieldMeaning
employmentIdThe employment the card is for
card.personalIdThe Personal ID as written on the card
card.forYearThe year the card is valid for. Typically from February of that year to January of the next
card.taxPercentThe percentage as a percentage: 50 means 50 %, not 0.5
card.incomeLimitThe income up to which taxPercent applies
card.taxPercent2The percentage for the part of the income above the limit
card.kinddefaultYearly, replacement, noWithholdingHousehold, others, historical, noTaxCard or auto
card.validityThe validity dates as expressed on the card

Saving a card for an employment that already has paid calculations can check them and add the difference to the card's income log.

The card is a separate Taxcard object, not a field of the employment or the calculation. When a calculation is recalculated, Salaxy picks the card valid for its payment date by the worker's Personal ID and copies it into the calculation.

Other endpoints ​

MethodPathPurpose
POST/v03/api/taxcards/calculateCalculate the withholding tax for a given card. Query: income, paymentDate (decides the tax year)
POST/v03/api/taxcards/reload-calcs/{id}Rebuild the income log from the paid calculations. Does not save
GET/v03/api/taxcards/shared-exists/{personalId}Before the employment exists: is there a card the worker has shared?
POST/v03/api/taxcards/approve/{method}Approve or reject a worker-shared card. method is assureWaiting, approve or reject. Query: ownedId or sharedUri

A card carries a state: new, approved, employerAdded, verifiedVero, sharedWaiting, sharedApproved, sharedRejected, sharedRejectedWithoutOpen or shared.

Rules to know ​

  • An employment left at status unknown is treated as active by the yearly tax card update. End employments properly: see Employees and employments.
  • A manual card is yours to keep current. Check forYear and validity against the salary dates you pay.

Test it ​

In the test environment, set info.taxcard to auto and read the card with GET /v03/api/taxcards/employment/{id}. To control what the Tax Administration answers for a test Personal ID, use the test-data tax card endpoint: see Test endpoints and test data. For a manual card, post the sample above for your test employment and check the result with POST /v03/api/taxcards/calculate.

Checklist ​

  • info.taxcard is auto unless you have a reason to hold the card yourself.
  • For a manual card, info.taxcard is manual and the card has a forYear and validity matching the salary dates.
  • You post percentages as percentages (10, not 0.1).
  • Ended employments are set to archived, so the yearly update treats them as ended.

Next: Dimensions (cost centres)

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.