Appearance
Worktime import
Worktime software already knows who worked how much. Import moves that data into Salaxy as rows on salary calculations in a draft payroll, so the payroll only has to be reviewed and paid. It is an optional REST part of an embedded white label integration (build path 1), and works the same when you build your own UI (build path 2).
Examples use the test environment; see Environments for demo and production.
Which fits you?
Import through the REST API
Fits when your system can call Salaxy directly. Live.
REST API: how it works
Two steps: make sure the employees exist, then post the rows.
| Method | Path | Purpose |
|---|---|---|
POST | /v03/api/import/workers-check | Check that workers exist. The id can be a Salaxy worker id, an employment id or a Personal ID |
POST | /v03/api/import/workers | Create or assure employments in bulk |
POST | /v03/api/import/calculations | Add calculations with rows to a new or existing payroll |
The calculation import never creates workers or employments. Create them first with Employees and employments or /import/workers, or every calculation fails.
Post an array. Each item is one calculation for one worker:
http
POST /v03/api/import/calculations?isMerge=true&rowMergeOption=removeImportedRows&sourceId=hours-2026-04 HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer eyJhbGc...
Content-Type: application/json
[
{
"officialId": "1234567-8",
"parameters": { "payroll": { "input": { "title": "Hours April 2026" } } },
"item": {
"worker": { "paymentData": { "socialSecurityNumber": "190372-942M" } },
"workflow": { "salaryDate": "2026-05-05" },
"info": { "workStartDate": "2026-04-01", "workEndDate": "2026-04-30" },
"rows": [
{ "rowType": "hourlySalary", "message": "Hours in April", "count": 152, "price": 18, "unit": "hours" }
]
}
}
]| Field | Meaning |
|---|---|
officialId | The employer's business ID. Optional: it defaults to the company you act as. If you act for several companies, always send it, or the calculation is booked on the account you act as |
item.worker.paymentData.socialSecurityNumber | The worker's Personal ID. Required |
item.worker.employmentId | The employment. Optional. Without it Salaxy picks the best match |
item.workflow.salaryDate | The salary date. Empty or invalid: Salaxy computes one |
item.info.workStartDate, workEndDate | The work period |
parameters.payroll.input.title | The payroll title. Empty: Palkkalaskelmat yyyy-MM-dd |
item.rows[] | The rows. rowType and price are what a row needs; count defaults to 1 |
The response is the same array with validation and result on each item. result.status is success, warning, error or ignored.
Query options of /v03/api/import/calculations. Send isMerge=true: rowMergeOption and the sourceId stamping below apply only in merge mode.
| Option | Effect on an existing calculation |
|---|---|
isMerge=true | Merge the posted rows into the worker's existing calculation in the payroll, as the options below say |
rowMergeOption=removeAllRows | Replace all rows with the posted ones |
rowMergeOption=removeImportedRows | Replace only rows from the same dataset (same sourceId). sourceId is required with this option |
| (not set) | Append the posted rows |
sourceId | Dataset id, stamped on every row without its own sourceId |
applyEmploymentDefaultRows | Also add the salary default rows of the employment |
The importer used by the Salaxy user interface sends isMerge: true, rowMergeOption: "removeAllRows" and applyEmploymentDefaultRows: false.
Import through the Data Agent (MCP)
Fits when an AI agent maps and loads the data instead of code you write. Coming
Data Agent: how it works
The Data Agent is the MCP server for Finnish payroll that brings payroll data in from other systems: import plans, source datasets, transformations and import runs. Its endpoints are published when it opens. Until then use the REST API. See MCP servers and MCP or REST?.
How the REST import behaves
- The payroll is found by company, salary date and title, among draft payrolls only. If none matches, a new payroll is created. Re-importing after the payroll has left draft creates a second payroll with the same title and salary date.
- A worker has one calculation per payroll. Inside the payroll, an existing calculation for the same Personal ID is updated, not duplicated.
- Each Personal ID may appear once in one request. The check ignores the company, so the same person employed by two customers must go in separate requests.
- Employments are found through the search index. An employment created moments before the import may not be found yet, and the calculation then fails with a missing-worker error. Retry after a short wait.
- Validation per calculation: the Personal ID is present and valid;
officialIdis valid, the company exists and you have access to it; the employment exists. Failures come back invalidation, one calculation at a time. - Several employments for one person: without
item.worker.employmentId, Salaxy ranks them: not terminated, valid on the salary date, closest start date, closest end date, newest. Send the employment id when a worker can have more than one. info.paymentChannelon a calculation overwrites the payroll's channel. Mixed values in one payroll: the last wins.- Row source ids: with
isMerge=true, a row withoutsourceIdgets the request'ssourceId, or the calculation id. Per-row source ids can be set only through the API. - Re-runs: post the same
sourceIdwithremoveImportedRowsto replace what a previous run imported, without touching rows added by hand. See Idempotency.
Working-time rows
Pay for working time is a row like any other. Three row types hold the time-based additions:
rowType | Use |
|---|---|
workingTimeCompensation | One compensation, reported under the code of its data.kind (for example eveningWorkCompensation, saturdayPay, sundayWorkCompensation, overtimeCompensation, nightWorkAllowance) |
hourlySalaryWithWorkingTimeCompensation | An hourly salary and its compensation on one row; the compensation is priced as a percentage of the hourly rate |
tesWorktimeShortening | The construction-sector separate salary component |
json
{
"rowType": "workingTimeCompensation",
"message": "Evening work compensation",
"count": 12,
"price": 2.10,
"data": { "kind": "eveningWorkCompensation" }
}- Salaxy sets no rates. No Salaxy dataset holds the amounts of these additions: they come from the applicable collective agreement. Your system sends the price; Salaxy does not know which agreement applies and does not check the amount.
- Send
data.kind. AworkingTimeCompensationrow without a kind is not reported to the Incomes Register. - One kind per
hourlySalaryWithWorkingTimeCompensationrow. For several kinds on one payslip, send one row per kind. - The plain rows
overtime,eveningAddition,nightimeAddition,saturdayAdditionandsundayWorkreport the same codes as lump sums. Prefer them for an amount typed by a person, and the compensation row when the code comes from an integration.
All row types are in the REST reference.
Test it
- Create a test employment (Employees and employments).
- Post the sample above with
isMerge=true,rowMergeOption=removeImportedRowsand asourceId, using your test company's business ID. - Check
result.status, then find the draft payroll by its title and salary date: it should hold one calculation with your row. - Post the same request again. The payroll and the calculation are reused; the row is replaced, not doubled.
Checklist
- Employments exist before the import. The import never creates them.
- Each request has each Personal ID once.
officialIdis always sent when you act for more than one company.- You use
isMerge=true, a stablesourceIdper dataset andremoveImportedRows, so a re-run replaces rows. - You read
result.statusandvalidationfor every item. - Working-time rows carry
data.kindand a price from the collective agreement.

