Appearance
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
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Identifier of the tax card |
income | query | number | New salary or other income, for which the widthholding tax is calculated. | |
paymentDate | query | string | Date 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
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
income | query | number | New salary or other income, for which the widthholding tax is calculated. | |
paymentDate | query | string | Date 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
$search | query | string | ||
$filter | query | string | Specifies the logic to pull back a subset of records. | |
$orderby | query | string | Specifies the values used to sort the collection of entries. | |
$select | query | string | The $select system query option allows the clients to requests a limited set of properties for each entry. | |
$top | query | number | Specifies the subset of entries by count. | |
$skip | query | number | Specifies the count of entries to skip. | |
$count | query | boolean | Indicates 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
calcDiffCheck | query | TaxcardCalcDiffCheck | Defines 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Unique identifier for the object |
calcDiffCheck | query | TaxcardCalcDiffCheck | Defines 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
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Unique 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).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
personalId | query | string | Personal ID for which the auto taxcard is set. If null, the current user is used: Must be a Worker account. | |
taxPercentMinimum | query | number | A 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. | |
salaryDate | query | string | The 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
taxcardIds | query | string[] | List of taxcards ids that should be checked | |
salaryDate | query | string | The salary date for which the taxcard is fetched. If null, uses today. | |
forceUpdate | query | boolean | If 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Identifier 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Identifier 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
method | path | TaxcardApprovalMethod | yes | Method 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). |
ownedId | query | string | Taxcard that will be approved / rejected. This an ID of the local copy (Employer / current account is owner). Either ownerId or sharedUri is required. | |
sharedUri | query | string | Taxcard 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).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
paymentDate | query | string | Payment 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
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
$search | query | string | ||
$filter | query | string | Specifies the logic to pull back a subset of records. | |
$orderby | query | string | Specifies the values used to sort the collection of entries. | |
$select | query | string | The $select system query option allows the clients to requests a limited set of properties for each entry. | |
$top | query | number | Specifies the subset of entries by count. | |
$skip | query | number | Specifies the count of entries to skip. | |
$count | query | boolean | Indicates 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Employent ID |
paymentDate | query | string | Payment 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).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
personalId | path | string | yes | Personal 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
paymentDate | query | string | Payment 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. | |
$search | query | string | ||
$filter | query | string | Specifies the logic to pull back a subset of records. | |
$orderby | query | string | Specifies the values used to sort the collection of entries. | |
$select | query | string | The $select system query option allows the clients to requests a limited set of properties for each entry. | |
$top | query | number | Specifies the subset of entries by count. | |
$skip | query | number | Specifies the count of entries to skip. | |
$count | query | boolean | Indicates 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
paymentDate | path | string | yes | Payment 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. |
$search | query | string | ||
$filter | query | string | Specifies the logic to pull back a subset of records. | |
$orderby | query | string | Specifies the values used to sort the collection of entries. | |
$select | query | string | The $select system query option allows the clients to requests a limited set of properties for each entry. | |
$top | query | number | Specifies the subset of entries by count. | |
$skip | query | number | Specifies the count of entries to skip. | |
$count | query | boolean | Indicates 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

