Appearance
Versions and changes
The REST API has two versions in the same URL space: /v03/ and /v04/. This page says which one to build on, what changes when you move, and what changed recently. One exception: the Pro API for accounting firms is also served under /v01/api/pro/..., and the site's Pro guide uses that path. Examples use the test environment; see Environments for demo and production.
Start on v03
Salaxy API v03 is the current version. Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version. Reference for v04 (beta).
Where to read each version
| Reference | OpenAPI document | |
|---|---|---|
| v03 | REST API reference | /openapi/salaxy-03.json |
| v04 | REST API reference v04 | /openapi/salaxy-04.json |
The API serves its own OpenAPI documents at /openapi/v03.json and /openapi/v04.json on each API host, for example https://test-secure.salaxy.com/openapi/v03.json. The earlier addresses under /docs/swagger/ no longer work.
From v03 to v04
Apart from the changes below, a v04 endpoint has the same path, parameters and models as in v03. To move a call, change /v03/ to /v04/ in the URL. v03 and v04 accept the same access token, so one integration can call both.
Payroll
The payroll endpoints are redesigned. In v03, most payroll actions are separate commands that take the whole payroll object. In v04, the calculations and invoices of a payroll are sub-resources of that payroll, and each call sends only what changes.
| v03 | v04 | Notes |
|---|---|---|
GET /v03/api/payroll/odata | GET /v04/api/payroll | The same OData list. GET /v03/api/payroll already works the same way |
POST /v03/api/payroll/add-employment | POST /v04/api/payroll/{id}/employments | Body is an array of employment ids. The response is the added calculations as CalculationListItem objects, not the payroll |
POST /v03/api/payroll/add-calc | POST /v04/api/payroll/{id}/calcs | Send the calculation ids in ids |
POST /v03/api/payroll/{id}/calcs | POST /v04/api/payroll/{id}/calcs | Same path, different contract. See below |
POST /v03/api/payroll/delete-calc | DELETE /v04/api/payroll/{id}/calcs/{calcId}?delete=true | One calculation per call. The calculation is deleted |
POST /v03/api/payroll/unlink-calc | DELETE /v04/api/payroll/{id}/calcs/{calcId} | One calculation per call. Without delete=true it is only removed from the payroll |
GET /v03/api/payroll/cancel/{id} | POST /v04/api/payroll/{id}/cancel-invoices | Body is an array of the calculation ids to cancel |
POST /v03/api/payroll/validate | none | No v04 equivalent. Keep using v03 |
GET /v03/api/payroll/{id}/absences | none | No v04 equivalent. Keep using v03 |
New in v04:
| Endpoint | Purpose |
|---|---|
GET /v04/api/payroll/{id}/calcs | Lists the calculations of the payroll. Supports OData queries |
POST /v04/api/payroll/{id}/preview-invoices | Previews the invoices for the given calculations |
POST /v04/api/payroll/{id}/create-invoices | Creates the invoices for the given calculations |
The invoice endpoints use the payment channel of the payroll (input.paymentChannel), so the URL has no channel. The body is an array of calculation ids. The v03 invoice endpoints, for example POST /v04/api/invoices/create-for-payroll/{channel}/{payrollId}, also work in v04 unchanged.
http
POST https://test-secure.salaxy.com/v04/api/payroll/{payrollId}/create-invoices
Authorization: Bearer {token}
Content-Type: application/json
["{calcId1}", "{calcId2}"]Saving calculations
POST /payroll/{id}/calcs has the same path in both versions, but the request and the response differ:
| v03 | v04 | |
|---|---|---|
| Request body | One Calculation object | A PayrollCalculationsCollection: ids (existing calculations to add) and objects (calculations to add or update) |
| Response | The saved Calculation | An array of CalculationListItem objects |
http
POST https://test-secure.salaxy.com/v04/api/payroll/{payrollId}/calcs
Authorization: Bearer {token}
Content-Type: application/json
{
"ids": ["{calcId1}", "{calcId2}"]
}Options
Some v04 payroll endpoints take an optional options object. Send its fields as ordinary query parameters, for example ?excludePeriodicInvoices=true.
| Endpoint | Options model | Fields |
|---|---|---|
POST /v04/api/payroll | PayrollSaveOptions | applyEmploymentDefaultRows |
POST /v04/api/payroll/{id}/calcs | PayrollCalculationsSaveOptions | isMerge, rowMergeOption, sourceId, applyEmploymentDefaultRows, applyWorktime |
.../preview-invoices, .../create-invoices, .../cancel-invoices | PayrollInvoicesOptions | excludePeriodicInvoices |
Reports
These report endpoints are not in v04. Keep using v03 for them.
| v03 endpoint | Notes |
|---|---|
GET /v03/api/reports/accounting/{refDate} | Monthly or yearly AccountingData for an accounting target |
GET and POST /v03/api/reports/accounting | AccountingData for a set of calculations |
GET /v03/api/reports/accounting/{refDate}/holiday-pay-debt | Holiday pay debt as ledger entries. The report shape, GET /v04/api/reports/holiday-pay-debt/{refDate}, is in v04 |
GET /v03/api/reports/validate/pay-certificate/{id} | Validates a pay certificate request |
GET /v04/api/reports/data/accounting/{tableType} and GET /v04/api/reports/data/accounting/{tableType}/{refDate} are in both versions. They return an AccountingReportTable, a different model from AccountingData, and take no accounting target. They do not replace the endpoints above. See Accounting data.
New in v04
| Area | Endpoints |
|---|---|
| Calculation corrections | /v04/api/calculations/correction/... |
| Company authorisation | POST /v04/api/company-authorization/link creates a start link that sends a company representative to the authorisation flow. For testing without credentials, see Test endpoints and test data |
| Data funnel | /v04/api/data-funnel/...: import data from files and rows through plans, runs and transformations. See Limits for the file upload |
| Overview | GET /v04/api/overview/all, GET /v04/api/overview/welcome-worker |
| Payment channel config | /v04/api/settings/payment-channels/{channel}/config: see Company settings. Errors are problem details |
| Pro | /v04/api/pro/...: the Pro API, in the v04 Pro tag. The same endpoints are served under /v01/api/pro/..., which the Pro guide uses |
Endpoints for creating and changing test data are listed in Test endpoints and test data.
Which versions does an endpoint serve
- Availability is per endpoint. Two endpoints of one controller can serve different versions. Check the endpoint in the OpenAPI document of the version you call, not its neighbour.
- An unversioned request resolves to v03.
- Test can be ahead of production. An endpoint in the test OpenAPI document may not be in production yet. See Environments.
Changelog
Newest first. Changes in the API may affect your integration. Added to the reference only grows the reference: a client generated from it keeps working.
v03 changes
| Change | What to do |
|---|---|
The calculation row type script is renamed to info. An info row is for information only | Use info in rowType and accept info in responses. The reference still lists script, so code generated from an earlier file compiles |
Employment.accruals is no longer used. The API does not store accrued time on the employment | Do not read or write accruals. For the remaining accrued holidays of an employment use GET /v03/api/holidays/employment/{employmentId}/available-holiday-accruals |
The OpenAPI documents come from a new tool. The API is the same, but model names and types differ from the earlier documents: for example PageResult_CalculationListItem_ is now PageResultOfCalculationListItem, and many fields are nullable | A client generated from an earlier document does not compile against a client generated from these documents. Regenerate and adjust |
Added to the v03 reference
Nothing is removed or renamed. You can regenerate a client without code changes, but make sure it accepts enum values it does not know yet.
| Area | Added |
|---|---|
| Calculator | POST /v03/api/calculator/addrow, deleterow, salary, setunionpayment, taxdeduction, work, workerset, recalculate-worktime/{type} |
| Tax cards | POST /v03/api/taxcards/approve/{method}, POST taxcards/file, GET taxcards/file/{id}, GET taxcards/issued, GET taxcards/my, GET taxcards/preview/{id}, GET taxcards/shared-exists/{personalId} |
| Invoices | POST /v03/api/invoices/create/{channel}/{id}, preview/{channel}, preview-by-id/{channel}, preview-for-payroll/{channel}/{payrollId} |
| Reports | GET and POST /v03/api/reports/data/accounting/{tableType}, GET reports/data/accounting/{tableType}/{refDate}, GET reports/pay-stats/{employmentId}, POST reports/pdf/{type} |
| Employments | GET /v03/api/employments/employing, GET employments/employing/{id} |
| Query parameters | $top and $skip on several list endpoints; version on the SEPA endpoints |
| Enum values | CalculationRowType: info; PayStatsPeriodLength: holidayYear |
| Fields | Several optional fields. Diff the OpenAPI document for the full list. Among them are the taxPercent fields on CalcTax and TaxcardResult |
Checklist
- You build on the current version, not on a beta version.
- You move one area at a time and test each in the test environment.
- You do not send a v03 payroll body to a v04 path that has a different contract.
- Your client accepts enum values it does not know yet.
- You regenerate your client from the OpenAPI document of the version you call.

