Appearance
REST API v04 by tag
Beta
Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version.
Every operation of Salaxy API v04 (beta) (Finland only), grouped by tag, as plain pages that search engines and LLM readers can fetch. The same content, interactive: REST API reference. Machine-readable: OpenAPI document.
| Tag | Operations | |
|---|---|---|
| Absences | 8 | Absences Controller provides CRUD functionality as well as additional methods for Absences objects |
| Account | 24 | Read and update access to Palkkaus-account: Person or Company accounts that are currently in use as well as Worker Accounts that are created under this account. |
| AccountingTarget | 5 | Views and updates accounting targets: integrated systems, CoA and rulesets that map the calculations to the CoA (Chart of Accounts). |
| AccountReset | 13 | Controller for resetting account data for testing purposes. |
| ApiCrudUtility | 1 | Various utility endpoints for all API CRUD objects. |
| BeneficialOwners | 2 | Views and updates beneficial owners and other beneficiaries of the company. |
| CalcCorrection | 6 | Endpoints for correcting readonly and paid calculations. |
| Calculations | 22 | Salary Calculations CRUD functionality as well as additional helper methods. |
| Calculator | 14 | Anonymous methods for calculating salary previews and testing without committing data to database. |
| CompanyAuthorizationLink | 2 | PARTNERS: Creates the links that send a company representative to the authorization flow. The partner account is read from the credentials of the caller, not fr |
| Dataset | 5 | Lists and edits datasets: Dataset models some arbitrary data that is stored in storage. |
| Employment | 9 | Employment relations between employers and workers. This is the primary method for Employers to manage their workers. |
| File | 6 | User-specific files and other files related functionality: Image processing, preview etc. |
| HolidayYears | 15 | Holiday Years Controller provides CRUD functionality as well as additional methods for Holiday Year objects |
| HouseholdYear | 11 | Views and updates household yearly deduction data. |
| Import | 8 | Controller for mass imports. |
| ImportPlan | 5 | CRUD for data funnel import plans: named, re-runnable bindings of a schema and a transformation. |
| ImportRun | 5 | CRUD for data funnel import runs: executions that post a target dataset to Salaxy. Execution itself is not part of this API. |
| InsuranceServices | 6 | API connecting to insurance partner services. |
| Invoice | 23 | Invoices in Salaxy contect are the payments that should be made to pay the net salary and side costs. The service is for querying invoices and notifying them as |
| MessageThread | 10 | CRUD functionality as well as additional methods for Message threads. Messages thread groups together a set of related messages and/or attachments. |
| OnboardingApi | 8 | Functionality for Onboarding: The process where the user becomes a user of Salaxy service and an account is created for him / her / the company. |
| Orders | 1 | |
| Overview | 2 | Mainly read-only methods over all objects owned by the current account. |
| Partner | 4 | Methods restricted to Authroized partners. NOTE: With production data, these methods require Approved Partner status! |
| PaymentChannel | 23 | Payment channels are methods that hanlde salary payments: Paytrail / Palkkaus.fi Customer funds account handling, Finvoice, Accounting software, Banks Web Servi |
| PaymentChannelConfig | 4 | The payment channel config of the current company: its own values that a payment channel needs to pay for it, such as the ID the provider gave the company and t |
| PaymentMessage | 6 | Payment messages (maksuaineisto) of the current company: create from invoices, list, download, mark sent, resend, mark paid and cancel. Every call is scoped to |
| Payroll | 12 | Payroll Controller provides CRUD functionality as well as additional methods for Payroll objects |
| Pro | 26 | Methods for PRO users (accountants, integrated services), for fetching data accross multiple accounts and impersonating as different authorized acccounts: Fetch |
| Record | 9 | Views and updates account and employment records. |
| ReferenceObject | 10 | Reference object controller. For testing and development purposes only. This controller is a typical CRUD controller for business objects. The implementation is |
| Reports | 25 | Methods for Reporting: Initiating custom report creation, listing created reports (including preview, pdf and HTML) as well as creating demo reports with test d |
| RowUsecases | 22 | Strongly typed and stand-alone test methods for the calculation rows usecases. |
| ServiceModel | 5 | Views and updates partner service models. Service models customize the user interface, workflows, texts and other functionality for customer groups of partners. |
| Session | 2 | Login, logoff and information about the current session. |
| Settings | 21 | View and update settings for the service. |
| SourceDataset | 7 | CRUD for data funnel source datasets: uploaded sources normalised to flat JSON rows. |
| TargetDataset | 5 | CRUD for data funnel target datasets: materialised flat target rows of a transformation. |
| TaskDefinition | 5 | Views and updates the definitions of the scheduled or adhoc tasks that can perform automated actions. |
| TaskRun | 8 | Views and updates the runs of the scheduled or adhoc tasks that can perform automated actions. |
| Taxcards | 20 | Year 2019 version for taxcards. This API will be replaced by the new 2020 version in January 2020. The new version is labeled as V03 (3.0-rc in before release) |
| Template | 5 | Views and updates templates for business object creation. |
| Test | 20 | Test methods for various purposes. |
| TestData | 2 | Methods for modifying test data. Only available in test environment. |
| Transformation | 5 | CRUD for data funnel transformations: JSONata expressions mapping flat source rows to flat target rows. |
| Usecases | 6 | Views and updates usecases. Usecases are a way to define custom functionality and data for partner pusposes. |
| Version | 2 | Functionality to list and get versions from version history for api objects. |
| Workflow | 4 | Functionality to add and change workflow events for all the API objects that support workflows. |
The API rules
Every call follows these rules. Each has its own page.
REST authentication
How to get an access token for the Salaxy REST API (Finland) — which flow fits which integration, and how tokens work.
- Your production server uses the impersonation flow with a signed JWT; the password flow is for development and testing.
- Your private key stays on your server, never in a browser or a repository.
- Every call sends the token as
Authorization: Bearer <token>. - A
401triggers one new token (repeat the grant) and one retry: there are no refresh tokens, and a token lasts about 48 hours.
Full page: REST authentication
Errors
How the Salaxy REST API reports failures — one JSON error shape, a few HTTP statuses, no stable error codes. Branch on the status, not the message.
- Your code branches on the HTTP status, never on the
errortext. - A
401triggers one new token and one retry — not a loop. - A
5xxwithout a body is handled. messageHtmlis shown to a person when a400needs fixing by hand.
Full page: Errors
Queries and paging
OData-style queries on Salaxy REST list endpoints — $filter, $search, $orderby, and paging with nextPageLink. Avoid $top.
- Every list read follows
nextPageLinkuntil it is gone. - No
$topin a query that must return everything. - Full records are fetched by id when list-item fields are not enough.
Full page: Queries and paging
Retries and idempotency
How to make retried requests safe with the Salaxy REST API — no general idempotency key; use your own ids and look before you create.
- Every object you create carries your own id where the API allows one.
- A retry after a timeout searches before it creates.
- Payment commits are checked by status before any retry.
Full page: Retries and idempotency
Events and polling
The Salaxy REST API has no webhooks or push notifications today — poll the read endpoints. What to poll, and how often.
- One list query per interval, not one call per calculation.
- Final statuses stop the polling for that object.
- An alert fires when a payment stays
paymentStartedlonger than your channel normally takes.
Full page: Events and polling
Versions and changes
Which Salaxy REST API version to build on, how v04 differs from v03, how to move one area at a time, and what changed in the v03 reference recently.
- 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.
Full page: Versions and changes

