Skip to content

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).

One host, one token, two API versionsYour integration calls the Salaxy API host with one access token. The same host serves two versions side by side. The v03 path serves every area of the API. The v04 path serves mostly the same endpoints, with the payroll endpoints redesigned. You can move one area at a time.YOUR SYSTEMOne access token/v03/api/...Every area, including accounting data.Payroll actions as separate commands./v04/api/...Mostly the same endpoints, redesigned payroll.Move one area at a time.
v03 and v04 run on the same hosts and accept the same token. The note above says which version to build on; move area by area.

Where to read each version ​

ReferenceOpenAPI document
v03REST API reference/openapi/salaxy-03.json
v04REST 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.

v03v04Notes
GET /v03/api/payroll/odataGET /v04/api/payrollThe same OData list. GET /v03/api/payroll already works the same way
POST /v03/api/payroll/add-employmentPOST /v04/api/payroll/{id}/employmentsBody is an array of employment ids. The response is the added calculations as CalculationListItem objects, not the payroll
POST /v03/api/payroll/add-calcPOST /v04/api/payroll/{id}/calcsSend the calculation ids in ids
POST /v03/api/payroll/{id}/calcsPOST /v04/api/payroll/{id}/calcsSame path, different contract. See below
POST /v03/api/payroll/delete-calcDELETE /v04/api/payroll/{id}/calcs/{calcId}?delete=trueOne calculation per call. The calculation is deleted
POST /v03/api/payroll/unlink-calcDELETE /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-invoicesBody is an array of the calculation ids to cancel
POST /v03/api/payroll/validatenoneNo v04 equivalent. Keep using v03
GET /v03/api/payroll/{id}/absencesnoneNo v04 equivalent. Keep using v03

New in v04:

EndpointPurpose
GET /v04/api/payroll/{id}/calcsLists the calculations of the payroll. Supports OData queries
POST /v04/api/payroll/{id}/preview-invoicesPreviews the invoices for the given calculations
POST /v04/api/payroll/{id}/create-invoicesCreates 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:

v03v04
Request bodyOne Calculation objectA PayrollCalculationsCollection: ids (existing calculations to add) and objects (calculations to add or update)
ResponseThe saved CalculationAn 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.

EndpointOptions modelFields
POST /v04/api/payrollPayrollSaveOptionsapplyEmploymentDefaultRows
POST /v04/api/payroll/{id}/calcsPayrollCalculationsSaveOptionsisMerge, rowMergeOption, sourceId, applyEmploymentDefaultRows, applyWorktime
.../preview-invoices, .../create-invoices, .../cancel-invoicesPayrollInvoicesOptionsexcludePeriodicInvoices

Reports ​

These report endpoints are not in v04. Keep using v03 for them.

v03 endpointNotes
GET /v03/api/reports/accounting/{refDate}Monthly or yearly AccountingData for an accounting target
GET and POST /v03/api/reports/accountingAccountingData for a set of calculations
GET /v03/api/reports/accounting/{refDate}/holiday-pay-debtHoliday 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 ​

AreaEndpoints
Calculation corrections/v04/api/calculations/correction/...
Company authorisationPOST /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
OverviewGET /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 ​

ChangeWhat to do
The calculation row type script is renamed to info. An info row is for information onlyUse 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 employmentDo 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 nullableA 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.

AreaAdded
CalculatorPOST /v03/api/calculator/addrow, deleterow, salary, setunionpayment, taxdeduction, work, workerset, recalculate-worktime/{type}
Tax cardsPOST /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}
InvoicesPOST /v03/api/invoices/create/{channel}/{id}, preview/{channel}, preview-by-id/{channel}, preview-for-payroll/{channel}/{payrollId}
ReportsGET and POST /v03/api/reports/data/accounting/{tableType}, GET reports/data/accounting/{tableType}/{refDate}, GET reports/pay-stats/{employmentId}, POST reports/pdf/{type}
EmploymentsGET /v03/api/employments/employing, GET employments/employing/{id}
Query parameters$top and $skip on several list endpoints; version on the SEPA endpoints
Enum valuesCalculationRowType: info; PayStatsPeriodLength: holidayYear
FieldsSeveral 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.

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.