# REST API by tag

Every operation of Salaxy API v03 (**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.md). Machine-readable: [OpenAPI document](https://code.salaxy.com/openapi/salaxy-03.json).

| Tag | Operations | |
|---|---|---|
| [Absences](https://code.salaxy.com/reference/rest/absences.md) | 8 | Absences Controller provides CRUD functionality as well as additional methods for Absences objects |
| [Account](https://code.salaxy.com/reference/rest/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/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/accountreset.md) | 13 | Controller for resetting account data for testing purposes. |
| [ApiCrudUtility](https://code.salaxy.com/reference/rest/apicrudutility.md) | 1 | Various utility endpoints for all API CRUD objects. |
| [BeneficialOwners](https://code.salaxy.com/reference/rest/beneficialowners.md) | 2 | Views and updates beneficial owners and other beneficiaries of the company. |
| [Calculations](https://code.salaxy.com/reference/rest/calculations.md) | 22 | Salary Calculations CRUD functionality as well as additional helper methods. |
| [Calculator](https://code.salaxy.com/reference/rest/calculator.md) | 14 | Anonymous methods for calculating salary previews and testing without committing data to database. |
| [Dataset](https://code.salaxy.com/reference/rest/dataset.md) | 5 | Lists and edits datasets: Dataset models some arbitrary data that is stored in storage. |
| [Employment](https://code.salaxy.com/reference/rest/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/file.md) | 6 | User-specific files and other files related functionality: Image processing, preview etc. |
| [HolidayYears](https://code.salaxy.com/reference/rest/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/householdyear.md) | 11 | Views and updates household yearly deduction data. |
| [Import](https://code.salaxy.com/reference/rest/import.md) | 8 | Controller for mass imports. |
| [InsuranceServices](https://code.salaxy.com/reference/rest/insuranceservices.md) | 6 | API connecting to insurance partner services. |
| [Invoice](https://code.salaxy.com/reference/rest/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/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/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. |
| [Partner](https://code.salaxy.com/reference/rest/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/paymentchannel.md) | 23 | Payment channels are methods that hanlde salary payments: Paytrail / Palkkaus.fi Customer funds account handling, Finvoice, Accounting software, Banks Web Servi |
| [PaymentMessage](https://code.salaxy.com/reference/rest/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/payroll.md) | 14 | Payroll Controller provides CRUD functionality as well as additional methods for Payroll objects |
| [Record](https://code.salaxy.com/reference/rest/record.md) | 9 | Views and updates account and employment records. |
| [ReferenceObject](https://code.salaxy.com/reference/rest/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/reports.md) | 32 | 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/rowusecases.md) | 22 | Strongly typed and stand-alone test methods for the calculation rows usecases. |
| [ServiceModel](https://code.salaxy.com/reference/rest/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/session.md) | 2 | Login, logoff and information about the current session. |
| [Settings](https://code.salaxy.com/reference/rest/settings.md) | 21 | View and update settings for the service. |
| [TaskDefinition](https://code.salaxy.com/reference/rest/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/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/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/template.md) | 5 | Views and updates templates for business object creation. |
| [Test](https://code.salaxy.com/reference/rest/test.md) | 20 | Test methods for various purposes. |
| [TestData](https://code.salaxy.com/reference/rest/testdata.md) | 2 | Methods for modifying test data. Only available in test environment. |
| [Usecases](https://code.salaxy.com/reference/rest/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/version.md) | 2 | Functionality to list and get versions from version history for api objects. |
| [Workflow](https://code.salaxy.com/reference/rest/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)
