Skip to content

Taxcards ​

Beta

Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version.

Year 2019 version for taxcards. This API will be replaced by the new 2020 version in January 2020. The new version is labeled as V03 (3.0-rc in before release) and old V02.

Salaxy API v04 (beta), Finland only. 20 operations. Interactive version: REST API reference. Machine-readable: OpenAPI document.

The reference wins

These pages are generated from the OpenAPI document. If a guide and this reference disagree about a field, follow the reference. Error responses are not in the document — see Errors.

GET /v04/api/taxcards/calculate/{id} ​

Calculates the widhholding tax based on a given tax card

ParameterInTypeRequiredDescription
idpathstringyesIdentifier of the tax card
incomequerynumberNew salary or other income, for which the widthholding tax is calculated.
paymentDatequerystringDate of payment (typically SalaryDate) determines the taxation year.

Response: TaxcardResult

Try it: interactive reference

POST /v04/api/taxcards/calculate ​

Calculates the widhholding tax based on a given tax card

ParameterInTypeRequiredDescription
incomequerynumberNew salary or other income, for which the widthholding tax is calculated.
paymentDatequerystringDate of payment (typically SalaryDate) determines the taxation year.

Request body: Taxcard (required)

Response: TaxcardResult

Try it: interactive reference

GET /v04/api/taxcards ​

Performs an OData query to the search index.

ParameterInTypeRequiredDescription
$searchquerystring
$filterquerystringSpecifies the logic to pull back a subset of records.
$orderbyquerystringSpecifies the values used to sort the collection of entries.
$selectquerystringThe $select system query option allows the clients to requests a limited set of properties for each entry.
$topquerynumberSpecifies the subset of entries by count.
$skipquerynumberSpecifies the count of entries to skip.
$countquerybooleanIndicates whether or not to include a total entry count.

Response: PageResultOfTaxcardListItem

Try it: interactive reference

POST /v04/api/taxcards ​

Updates or creates a new object. Paid calculations may be checked and added as Diff rows depending on taxcardOnly parameter.

ParameterInTypeRequiredDescription
calcDiffCheckqueryTaxcardCalcDiffCheckDefines the behavior of how to check and handle existing paid calculations when saving the taxcard.

Request body: Taxcard (required)

Response: Taxcard

Try it: interactive reference

GET /v04/api/taxcards/{id} ​

Gets a single object based on identier. By default also returns Diff if paid calculations are different in database than in the taxcard.

ParameterInTypeRequiredDescription
idpathstringyesUnique identifier for the object
calcDiffCheckqueryTaxcardCalcDiffCheckDefines the behavior of how to check and handle existing paid calculations. Default is "getDiff" where the system fetches the paid calculations in the database and adds them as Diff-rows. Note that "commitDiff" is not currently supported. May later be supported if necessary.

Response: Taxcard

Try it: interactive reference

DELETE /v04/api/taxcards/{id} ​

Deletes an object from the storage

ParameterInTypeRequiredDescription
idpathstringyesUnique identifier for the object.

Response: string

Try it: interactive reference

GET /v04/api/taxcards/new ​

Factory method that creates a new object

Response: Taxcard

Try it: interactive reference

POST /v04/api/taxcards/auto-set ​

Sets the automatic taxcard on for the given personal ID. Method will make the request to tax authorities API immediately. NOTE: In current implementation, the income type is always Salary (00024: Palkkaa).

ParameterInTypeRequiredDescription
personalIdquerystringPersonal ID for which the auto taxcard is set. If null, the current user is used: Must be a Worker account.
taxPercentMinimumquerynumberA Worker may request a minimum percent that is deducted even if the effective tax percent would be lower. This can be used if Worker knows that he/she will be earning more in the year than what was estimated when the taxcard was created.
salaryDatequerystringThe first salary date for which the taxcard is fetched. If null, uses today.

Response: Taxcard

Try it: interactive reference

POST /v04/api/taxcards/auto-refresh ​

Checks automatic taxcards from the Tax authorities API: If the taxcard has been checked within 2 days, does nothing. If there are no changes, updates the LastChecked date only. If there are changes, creates a new taxcard container and returns it instead.

ParameterInTypeRequiredDescription
taxcardIdsquerystring[]List of taxcards ids that should be checked
salaryDatequerystringThe salary date for which the taxcard is fetched. If null, uses today.
forceUpdatequerybooleanIf true, skips the 2 day rule and always checks from the tax athorities API.

Response: TaxcardListItem[]

Try it: interactive reference

GET /v04/api/taxcards/file/{id} ​

Gets a file download (typically PDF or original image) for the taxcard. Shows owned taxcards, taxcards that have the same personal ID as Worker account or that are copies of Worker account's shared card.

ParameterInTypeRequiredDescription
idpathstringyesIdentifier of the taxcard if owned. For a shared card or employer added card, may also be the URI of the Employer copy if the current user is the Worker account with the personal ID or owns the original copy.

Response: File stream or 404 error if not found.

Try it: interactive reference

GET /v04/api/taxcards/preview/{id} ​

Gets a file preview (typically png) for the taxcard. Shows owned taxcards, taxcards that have the same personal ID as Worker account or that are copies of Worker account's shared card.

ParameterInTypeRequiredDescription
idpathstringyesIdentifier of the taxcard if owned. For a shared card or employer added card, may also be the URI of the Employer copy if the current user is the Worker account with the personal ID or owns the original copy.

Response: File stream or 404 error if not found.

Try it: interactive reference

POST /v04/api/taxcards/reload-calcs/{id} ​

Reloads the income log based on the calculations. Gets all the paid calculations that are relevant to this taxcard and lists them in the income log. This method does not yet save the changes.

ParameterInTypeRequiredDescription
idpathstringyes

Request body: Taxcard (required)

Response: The single object or null if none is found.

Try it: interactive reference

POST /v04/api/taxcards/approve/{method} ​

Sets the approval for a taxcard.

ParameterInTypeRequiredDescription
methodpathTaxcardApprovalMethodyesMethod of approval. AssureWaiting does not yet approve/reject. It just assures that there is a taxcard that can be viewed by the Employer. This information is stored in the database so that Worker can see who has looked at his/her taxcards (Data protetion / GDPR).
ownedIdquerystringTaxcard that will be approved / rejected. This an ID of the local copy (Employer / current account is owner). Either ownerId or sharedUri is required.
sharedUriquerystringTaxcard that will be approved / rejected. This an URI of the Shared taxcard (Worker / owner is part of the URI). Either ownerId or sharedUri is required.

Response: Taxcard

Try it: interactive reference

GET /v04/api/taxcards/my ​

Gets all the current taxcards for the current Worker account: The cards that the account has uploaded as well as the cards created by all Employers. This method can only be run for a personal account (not for a Company account).

ParameterInTypeRequiredDescription
paymentDatequerystringPayment date for which the validity (current card in use) is calculated. If null, Next workday is used. This may be changed to next default payment date without that being a breaking change.

Response: WorkerCurrentTaxcards

Try it: interactive reference

GET /v04/api/taxcards/issued ​

Performs an OData query to the search index. Returns all

ParameterInTypeRequiredDescription
$searchquerystring
$filterquerystringSpecifies the logic to pull back a subset of records.
$orderbyquerystringSpecifies the values used to sort the collection of entries.
$selectquerystringThe $select system query option allows the clients to requests a limited set of properties for each entry.
$topquerynumberSpecifies the subset of entries by count.
$skipquerynumberSpecifies the count of entries to skip.
$countquerybooleanIndicates whether or not to include a total entry count.

Response: PageResultOfTaxcardListItem

Try it: interactive reference

GET /v04/api/taxcards/employment/{id} ​

Gets all available / current taxcards for an employment. By default, these taxcards are added by the Employer, but there may also be the latest taxcard added by the Worker.

ParameterInTypeRequiredDescription
idpathstringyesEmployent ID
paymentDatequerystringPayment date for which the validity (current card in use) is calculated. If null, Next workday is used. This may be changed to next default payment date without that being a breaking change.

Response: WorkerCurrentTaxcards

Try it: interactive reference

GET /v04/api/taxcards/shared-exists/{personalId} ​

For an employment relationship that is not yet created, allows checking if there is a shared taxcard. Returns true if there is a shared taxcard available for the given Personal ID. NOTE: There are unspecified and potentially changing restrictions on how many times this interface can be called to remove the risk of Phishing. If such restriciton hits, the IsError property will be true. In this case, you should currently create the employment relation and fetch the taxcard info after that. We may later introduce a "Are you robot" type of interface to go around this (if necessary).

ParameterInTypeRequiredDescription
personalIdpathstringyesPersonal ID of the Worker that will be added.

Response: SharedTaxcardExistsResult

Try it: interactive reference

GET /v04/api/taxcards/current ​

Gets a list of all non-terminated employments of the employer and resolves their current taxcards. The current taxcards may be for the current year or for next year if the current date is either December or January.

ParameterInTypeRequiredDescription
paymentDatequerystringPayment date for which the validity (current card in use) is calculated. If null, Next workday is used. This may be changed to next default payment date without that being a breaking change.
$searchquerystring
$filterquerystringSpecifies the logic to pull back a subset of records.
$orderbyquerystringSpecifies the values used to sort the collection of entries.
$selectquerystringThe $select system query option allows the clients to requests a limited set of properties for each entry.
$topquerynumberSpecifies the subset of entries by count.
$skipquerynumberSpecifies the count of entries to skip.
$countquerybooleanIndicates whether or not to include a total entry count.

Response: PageResultOfTaxcardListItem

Try it: interactive reference

GET /v04/api/taxcards/current/{paymentDate} ​

Gets a list of all non-terminated employments of the employer and resolves their current taxcards for the payment date in the path. The current taxcards may be for the current year or for next year if the current date is either December or January.

ParameterInTypeRequiredDescription
paymentDatepathstringyesPayment date for which the validity (current card in use) is calculated. A value that is not a date is ignored, and the next workday is used.
$searchquerystring
$filterquerystringSpecifies the logic to pull back a subset of records.
$orderbyquerystringSpecifies the values used to sort the collection of entries.
$selectquerystringThe $select system query option allows the clients to requests a limited set of properties for each entry.
$topquerynumberSpecifies the subset of entries by count.
$skipquerynumberSpecifies the count of entries to skip.
$countquerybooleanIndicates whether or not to include a total entry count.

Response: PageResultOfTaxcardListItem

Try it: interactive reference

POST /v04/api/taxcards/file ​

Saves the tax card file for the user. In the future returns parsed data from the file.

Response: Tax card.

Try it: interactive reference

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.