Appearance
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.
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.
| Method | Path | Purpose |
|---|---|---|
POST | /v03/api/taxcards/auto-set | Fetch and set the automatic card now. Query: personalId, taxPercentMinimum, salaryDate (default: today) |
POST | /v03/api/taxcards/auto-refresh | Check cards again. Query: taxcardIds, salaryDate, forceUpdate |
GET | /v03/api/taxcards/current | The 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=trueskips 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
currentcan 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.
| Method | Path | Purpose |
|---|---|---|
GET | /v03/api/taxcards/new | A blank card to fill in |
POST | /v03/api/taxcards | Create or update a card |
GET | /v03/api/taxcards/{id} | Read one card |
DELETE | /v03/api/taxcards/{id} | Delete a card |
GET | /v03/api/taxcards | Find 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" }
}
}| Field | Meaning |
|---|---|
employmentId | The employment the card is for |
card.personalId | The Personal ID as written on the card |
card.forYear | The year the card is valid for. Typically from February of that year to January of the next |
card.taxPercent | The percentage as a percentage: 50 means 50 %, not 0.5 |
card.incomeLimit | The income up to which taxPercent applies |
card.taxPercent2 | The percentage for the part of the income above the limit |
card.kind | defaultYearly, replacement, noWithholdingHousehold, others, historical, noTaxCard or auto |
card.validity | The 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
| Method | Path | Purpose |
|---|---|---|
POST | /v03/api/taxcards/calculate | Calculate 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
unknownis 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
forYearandvalidityagainst 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.taxcardisautounless you have a reason to hold the card yourself.- For a manual card,
info.taxcardismanualand the card has aforYearand 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.

