# 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](https://code.salaxy.com/white-label/index.md) integration (build path 1), and works the same when you build your own UI (build path 2).

Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Four 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. (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.

| 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](https://code.salaxy.com/integration/employments.md) 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](https://code.salaxy.com/reference/mcp.md) and [MCP or REST?](https://code.salaxy.com/about/mcp-or-rest.md).

## 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](https://code.salaxy.com/reference/idempotency.md).

## 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`.** 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](https://code.salaxy.com/reference/rest/import.md).

## Test it

1. Create a test employment ([Employees and employments](https://code.salaxy.com/integration/employments.md)).
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](https://code.salaxy.com/integration/payroll-lifecycle.md)
