Skip to content

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.

TagOperations
Absences8Absences Controller provides CRUD functionality as well as additional methods for Absences objects
Account24Read 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.
AccountingTarget5Views and updates accounting targets: integrated systems, CoA and rulesets that map the calculations to the CoA (Chart of Accounts).
AccountReset13Controller for resetting account data for testing purposes.
ApiCrudUtility1Various utility endpoints for all API CRUD objects.
BeneficialOwners2Views and updates beneficial owners and other beneficiaries of the company.
CalcCorrection6Endpoints for correcting readonly and paid calculations.
Calculations22Salary Calculations CRUD functionality as well as additional helper methods.
Calculator14Anonymous methods for calculating salary previews and testing without committing data to database.
CompanyAuthorizationLink2PARTNERS: 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
Dataset5Lists and edits datasets: Dataset models some arbitrary data that is stored in storage.
Employment9Employment relations between employers and workers. This is the primary method for Employers to manage their workers.
File6User-specific files and other files related functionality: Image processing, preview etc.
HolidayYears15Holiday Years Controller provides CRUD functionality as well as additional methods for Holiday Year objects
HouseholdYear11Views and updates household yearly deduction data.
Import8Controller for mass imports.
ImportPlan5CRUD for data funnel import plans: named, re-runnable bindings of a schema and a transformation.
ImportRun5CRUD for data funnel import runs: executions that post a target dataset to Salaxy. Execution itself is not part of this API.
InsuranceServices6API connecting to insurance partner services.
Invoice23Invoices 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
MessageThread10CRUD functionality as well as additional methods for Message threads. Messages thread groups together a set of related messages and/or attachments.
OnboardingApi8Functionality for Onboarding: The process where the user becomes a user of Salaxy service and an account is created for him / her / the company.
Orders1
Overview2Mainly read-only methods over all objects owned by the current account.
Partner4Methods restricted to Authroized partners. NOTE: With production data, these methods require Approved Partner status!
PaymentChannel23Payment channels are methods that hanlde salary payments: Paytrail / Palkkaus.fi Customer funds account handling, Finvoice, Accounting software, Banks Web Servi
PaymentChannelConfig4The 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
PaymentMessage6Payment messages (maksuaineisto) of the current company: create from invoices, list, download, mark sent, resend, mark paid and cancel. Every call is scoped to
Payroll12Payroll Controller provides CRUD functionality as well as additional methods for Payroll objects
Pro26Methods for PRO users (accountants, integrated services), for fetching data accross multiple accounts and impersonating as different authorized acccounts: Fetch
Record9Views and updates account and employment records.
ReferenceObject10Reference object controller. For testing and development purposes only. This controller is a typical CRUD controller for business objects. The implementation is
Reports25Methods for Reporting: Initiating custom report creation, listing created reports (including preview, pdf and HTML) as well as creating demo reports with test d
RowUsecases22Strongly typed and stand-alone test methods for the calculation rows usecases.
ServiceModel5Views and updates partner service models. Service models customize the user interface, workflows, texts and other functionality for customer groups of partners.
Session2Login, logoff and information about the current session.
Settings21View and update settings for the service.
SourceDataset7CRUD for data funnel source datasets: uploaded sources normalised to flat JSON rows.
TargetDataset5CRUD for data funnel target datasets: materialised flat target rows of a transformation.
TaskDefinition5Views and updates the definitions of the scheduled or adhoc tasks that can perform automated actions.
TaskRun8Views and updates the runs of the scheduled or adhoc tasks that can perform automated actions.
Taxcards20Year 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)
Template5Views and updates templates for business object creation.
Test20Test methods for various purposes.
TestData2Methods for modifying test data. Only available in test environment.
Transformation5CRUD for data funnel transformations: JSONata expressions mapping flat source rows to flat target rows.
Usecases6Views and updates usecases. Usecases are a way to define custom functionality and data for partner pusposes.
Version2Functionality to list and get versions from version history for api objects.
Workflow4Functionality 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 401 triggers 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 error text.
  • A 401 triggers one new token and one retry — not a loop.
  • A 5xx without a body is handled.
  • messageHtml is shown to a person when a 400 needs 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 nextPageLink until it is gone.
  • No $top in 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 paymentStarted longer 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

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.