Skip to content

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.

From worktime to payrollFour steps left to right. Your worktime system holds the hours. An import, through the REST API or the Data Agent, sends them to Salaxy. Salaxy puts them into a draft payroll as rows of salary calculations. The payroll is then reviewed and paid.Your worktimehours, pay rowsImportREST or Data AgentDraft payrollcalculationsReview, paypayroll lifecycle
The import creates draft calculations. Calculation, payment and filing are the same as for any other payroll.

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.

MethodPathPurpose
POST/v03/api/import/workers-checkCheck that workers exist. The id can be a Salaxy worker id, an employment id or a Personal ID
POST/v03/api/import/workersCreate or assure employments in bulk
POST/v03/api/import/calculationsAdd 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" }
      ]
    }
  }
]
FieldMeaning
officialIdThe 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.socialSecurityNumberThe worker's Personal ID. Required
item.worker.employmentIdThe employment. Optional. Without it Salaxy picks the best match
item.workflow.salaryDateThe salary date. Empty or invalid: Salaxy computes one
item.info.workStartDate, workEndDateThe work period
parameters.payroll.input.titleThe 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.

OptionEffect on an existing calculation
isMerge=trueMerge the posted rows into the worker's existing calculation in the payroll, as the options below say
rowMergeOption=removeAllRowsReplace all rows with the posted ones
rowMergeOption=removeImportedRowsReplace only rows from the same dataset (same sourceId). sourceId is required with this option
(not set)Append the posted rows
sourceIdDataset id, stamped on every row without its own sourceId
applyEmploymentDefaultRowsAlso 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; officialId is valid, the company exists and you have access to it; the employment exists. Failures come back in validation, 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.paymentChannel on a calculation overwrites the payroll's channel. Mixed values in one payroll: the last wins.
  • Row source ids: with isMerge=true, a row without sourceId gets the request's sourceId, or the calculation id. Per-row source ids can be set only through the API.
  • Re-runs: post the same sourceId with removeImportedRows to 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:

rowTypeUse
workingTimeCompensationOne compensation, reported under the code of its data.kind (for example eveningWorkCompensation, saturdayPay, sundayWorkCompensation, overtimeCompensation, nightWorkAllowance)
hourlySalaryWithWorkingTimeCompensationAn hourly salary and its compensation on one row; the compensation is priced as a percentage of the hourly rate
tesWorktimeShorteningThe 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. A workingTimeCompensation row without a kind is not reported to the Incomes Register.
  • One kind per hourlySalaryWithWorkingTimeCompensation row. For several kinds on one payslip, send one row per kind.
  • The plain rows overtime, eveningAddition, nightimeAddition, saturdayAddition and sundayWork report 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 ​

  1. Create a test employment (Employees and employments).
  2. Post the sample above with isMerge=true, rowMergeOption=removeImportedRows and a sourceId, using your test company's business ID.
  3. Check result.status, then find the draft payroll by its title and salary date: it should hold one calculation with your row.
  4. 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.
  • officialId is always sent when you act for more than one company.
  • You use isMerge=true, a stable sourceId per dataset and removeImportedRows, so a re-run replaces rows.
  • You read result.status and validation for every item.
  • Working-time rows carry data.kind and a price from the collective agreement.

Next: Payroll lifecycle and statuses

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.