# 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](https://code.salaxy.com/reference/rest-api-v04.md). Machine-readable: [OpenAPI document](https://code.salaxy.com/openapi/salaxy-04.json).

| Tag | Operations | |
|---|---|---|
| [Absences](https://code.salaxy.com/reference/rest/v04/absences.md) | 8 | Absences Controller provides CRUD functionality as well as additional methods for Absences objects |
| [Account](https://code.salaxy.com/reference/rest/v04/account.md) | 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](https://code.salaxy.com/reference/rest/v04/accountingtarget.md) | 5 | Views and updates accounting targets: integrated systems, CoA and rulesets that map the calculations to the CoA (Chart of Accounts). |
| [AccountReset](https://code.salaxy.com/reference/rest/v04/accountreset.md) | 13 | Controller for resetting account data for testing purposes. |
| [ApiCrudUtility](https://code.salaxy.com/reference/rest/v04/apicrudutility.md) | 1 | Various utility endpoints for all API CRUD objects. |
| [BeneficialOwners](https://code.salaxy.com/reference/rest/v04/beneficialowners.md) | 2 | Views and updates beneficial owners and other beneficiaries of the company. |
| [CalcCorrection](https://code.salaxy.com/reference/rest/v04/calccorrection.md) | 6 | Endpoints for correcting readonly and paid calculations. |
| [Calculations](https://code.salaxy.com/reference/rest/v04/calculations.md) | 22 | Salary Calculations CRUD functionality as well as additional helper methods. |
| [Calculator](https://code.salaxy.com/reference/rest/v04/calculator.md) | 14 | Anonymous methods for calculating salary previews and testing without committing data to database. |
| [CompanyAuthorizationLink](https://code.salaxy.com/reference/rest/v04/companyauthorizationlink.md) | 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](https://code.salaxy.com/reference/rest/v04/dataset.md) | 5 | Lists and edits datasets: Dataset models some arbitrary data that is stored in storage. |
| [Employment](https://code.salaxy.com/reference/rest/v04/employment.md) | 9 | Employment relations between employers and workers. This is the primary method for Employers to manage their workers. |
| [File](https://code.salaxy.com/reference/rest/v04/file.md) | 6 | User-specific files and other files related functionality: Image processing, preview etc. |
| [HolidayYears](https://code.salaxy.com/reference/rest/v04/holidayyears.md) | 15 | Holiday Years Controller provides CRUD functionality as well as additional methods for Holiday Year objects |
| [HouseholdYear](https://code.salaxy.com/reference/rest/v04/householdyear.md) | 11 | Views and updates household yearly deduction data. |
| [Import](https://code.salaxy.com/reference/rest/v04/import.md) | 8 | Controller for mass imports. |
| [ImportPlan](https://code.salaxy.com/reference/rest/v04/importplan.md) | 5 | CRUD for data funnel import plans: named, re-runnable bindings of a schema and a transformation. |
| [ImportRun](https://code.salaxy.com/reference/rest/v04/importrun.md) | 5 | CRUD for data funnel import runs: executions that post a target dataset to Salaxy. Execution itself is not part of this API. |
| [InsuranceServices](https://code.salaxy.com/reference/rest/v04/insuranceservices.md) | 6 | API connecting to insurance partner services. |
| [Invoice](https://code.salaxy.com/reference/rest/v04/invoice.md) | 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](https://code.salaxy.com/reference/rest/v04/messagethread.md) | 10 | CRUD functionality as well as additional methods for Message threads. Messages thread groups together a set of related messages and/or attachments. |
| [OnboardingApi](https://code.salaxy.com/reference/rest/v04/onboardingapi.md) | 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](https://code.salaxy.com/reference/rest/v04/orders.md) | 1 |  |
| [Overview](https://code.salaxy.com/reference/rest/v04/overview.md) | 2 | Mainly read-only methods over all objects owned by the current account. |
| [Partner](https://code.salaxy.com/reference/rest/v04/partner.md) | 4 | Methods restricted to Authroized partners. NOTE: With production data, these methods require Approved Partner status! |
| [PaymentChannel](https://code.salaxy.com/reference/rest/v04/paymentchannel.md) | 23 | Payment channels are methods that hanlde salary payments: Paytrail / Palkkaus.fi Customer funds account handling, Finvoice, Accounting software, Banks Web Servi |
| [PaymentChannelConfig](https://code.salaxy.com/reference/rest/v04/paymentchannelconfig.md) | 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](https://code.salaxy.com/reference/rest/v04/paymentmessage.md) | 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](https://code.salaxy.com/reference/rest/v04/payroll.md) | 12 | Payroll Controller provides CRUD functionality as well as additional methods for Payroll objects |
| [Pro](https://code.salaxy.com/reference/rest/v04/pro.md) | 26 | Methods for PRO users (accountants, integrated services), for fetching data accross multiple accounts and impersonating as different authorized acccounts: Fetch |
| [Record](https://code.salaxy.com/reference/rest/v04/record.md) | 9 | Views and updates account and employment records. |
| [ReferenceObject](https://code.salaxy.com/reference/rest/v04/referenceobject.md) | 10 | Reference object controller. For testing and development purposes only. This controller is a typical CRUD controller for business objects. The implementation is |
| [Reports](https://code.salaxy.com/reference/rest/v04/reports.md) | 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](https://code.salaxy.com/reference/rest/v04/rowusecases.md) | 22 | Strongly typed and stand-alone test methods for the calculation rows usecases. |
| [ServiceModel](https://code.salaxy.com/reference/rest/v04/servicemodel.md) | 5 | Views and updates partner service models. Service models customize the user interface, workflows, texts and other functionality for customer groups of partners. |
| [Session](https://code.salaxy.com/reference/rest/v04/session.md) | 2 | Login, logoff and information about the current session. |
| [Settings](https://code.salaxy.com/reference/rest/v04/settings.md) | 21 | View and update settings for the service. |
| [SourceDataset](https://code.salaxy.com/reference/rest/v04/sourcedataset.md) | 7 | CRUD for data funnel source datasets: uploaded sources normalised to flat JSON rows. |
| [TargetDataset](https://code.salaxy.com/reference/rest/v04/targetdataset.md) | 5 | CRUD for data funnel target datasets: materialised flat target rows of a transformation. |
| [TaskDefinition](https://code.salaxy.com/reference/rest/v04/taskdefinition.md) | 5 | Views and updates the definitions of the scheduled or adhoc tasks that can perform automated actions. |
| [TaskRun](https://code.salaxy.com/reference/rest/v04/taskrun.md) | 8 | Views and updates the runs of the scheduled or adhoc tasks that can perform automated actions. |
| [Taxcards](https://code.salaxy.com/reference/rest/v04/taxcards.md) | 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](https://code.salaxy.com/reference/rest/v04/template.md) | 5 | Views and updates templates for business object creation. |
| [Test](https://code.salaxy.com/reference/rest/v04/test.md) | 20 | Test methods for various purposes. |
| [TestData](https://code.salaxy.com/reference/rest/v04/testdata.md) | 2 | Methods for modifying test data. Only available in test environment. |
| [Transformation](https://code.salaxy.com/reference/rest/v04/transformation.md) | 5 | CRUD for data funnel transformations: JSONata expressions mapping flat source rows to flat target rows. |
| [Usecases](https://code.salaxy.com/reference/rest/v04/usecases.md) | 6 | Views and updates usecases. Usecases are a way to define custom functionality and data for partner pusposes. |
| [Version](https://code.salaxy.com/reference/rest/v04/version.md) | 2 | Functionality to list and get versions from version history for api objects. |
| [Workflow](https://code.salaxy.com/reference/rest/v04/workflow.md) | 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 `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](https://code.salaxy.com/security/rest-authentication.md)

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

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

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

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

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