Appearance
Employees and employments
In Salaxy an employee is an employment: the link between a worker (the person) and a customer company (the employer). Every salary calculation is built from one. This page is the full topic; the first call is in 3. Create employees.
Examples use the test environment; see Environments for demo and production. Authenticate as the employer (the customer company): see Impersonation.
The model
- Worker. The person, identified by Personal ID. Holds name, contact details and bank account. One worker can be employed by several companies. Once the worker registers with Salaxy, they maintain their own personal data.
- Employment. The link between one worker and one company. Holds the employment period, type, pension and insurance setup, tax card handling and salary defaults. There can be several employments for the same worker and company, over time or at once.
You never create a worker directly. Every save of an employment, create or update, first resolves the worker record and creates one if it cannot find it. The result is in info.workerAccountId.
Salaxy resolves the worker in this order:
info.workerAccountId, if your request carries it. This is the reliable route.- Otherwise Salaxy looks the Personal ID up among this company's employments in the search index, and reuses the worker record it finds there.
- Otherwise a new worker record is created from
identityand thedefaultcontact.
Keep info.workerAccountId from the create response and send it on every later employment for the same person. Rule 2 depends on the search index, which fills a while after a write. If you send only the Personal ID and the index has not caught up, a second employment lands on rule 3 and creates two worker records for one Personal ID. Nothing rejects this, so prevent it yourself.
Once the worker has registered, the employment reads isRegistered: true. The name, language and contact details you send then no longer overwrite the worker's own. Contact values that differ are kept on the employment as an employerOverride entry in contacts[].
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /v03/api/employments | Create (no id in the body) or update (with id). There is no PUT |
GET | /v03/api/employments | Find and list. OData query; see Queries |
GET | /v03/api/employments/{id} | Read one full employment |
GET | /v03/api/employments/active?date=YYYY-MM-DD | List the employments active on one day (default: today). Reads storage directly, not the search index |
DELETE | /v03/api/employments/{id} | Delete. For the test environment; in production, end the employment instead |
The list is scoped to the account you act as, so a plain GET /v03/api/employments returns only that company's employments.
Create
The request is in 3. Create employees. Field shapes that are easy to get wrong:
info.typeis the employment type:monthlySalary,hourlySalary,salaryand so on. A fixed-term employment is marked withinfo.isFixedTerm, not with a type.info.taxcardis a string:auto,manual,noTaxCardortaxAtSource. See Tax cards.info.pensionCalculationisemployeefor the standard employee pension.contacts[]entries have atype(default,workerAccount,employerOverride,foreign) and typed fields such asemailandtelephone.- Always send
info.startDate. It is not required to create, but without it the end date and ending reason of the employment are never reported to the Incomes Register, even though everything validates. You find out only when the employee leaves. info.sourceIdis your own employee id. It is exposed as the filterableexternalId.
Pension and insurance defaults can also come from Company settings.
Personal IDs
A Personal ID is six date digits, a century separator, a three-digit person number and a check character. A save fails with HTTP 400 and the title Invalid Personal ID if:
- neither
identity.personalIdnorinfo.workerAccountIdis in the body (the message shows a blank id); - the Personal ID does not parse (the message echoes the value).
A save that has to create a new worker record (rule 3) fails with HTTP 400 and the title Names are required if identity.firstName or identity.lastName is blank.
What does not parse:
- The separator must be one of
+ - A B C D E F U V W X Y.A-Fmean the 2000s,-andU-Ythe 1900s,+the 1800s. Look-alikes fail: an en dash (U+2013), a non-breaking hyphen (U+2011), spaces around the separator, a zero-width space. - The check character must be correct. Generate it with a Finnish Personal ID library.
- The date must be real:
310296fails even with a correct check character.
Leading and trailing whitespace is trimmed.
A temporary Personal ID has a person number of 900 or more, for example 190372-942M. It is valid and creating the employment works as usual. But the worker's postal address becomes mandatory before a calculation validates: send street, postalCode and city in the default contact. Without them the calculation saves as a draft with isValid: false and cannot be paid. The calculation errors are Calc.MissingWorkerContactStreet, Calc.MissingWorkerContactPostalCode and Calc.MissingWorkerContactCity. Street is reported first; the other two appear only after you fill it in.
The samples on this site use a temporary ID on purpose, so a real person's ID is never printed.
Find
Both lookups read a search index that fills a short while after a write. An employment is not findable the instant you create it, and an empty list does not prove the write failed.
http
GET /v03/api/employments?$filter=externalId eq 'client-emp-4711' HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer eyJhbGc...http
GET /v03/api/employments?$filter=otherPartyInfo/officialId eq '190372-942M' HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer eyJhbGc...- Your own id:
$filter=externalId eq '<info.sourceId>'. - Personal ID:
$filter=otherPartyInfo/officialId eq '<personal id>', an exact match.$search=other:<personal id>builds the same filter for you. A plain$search=<personal id>is a free-text search and can match other rows. - Paging: omit
$topand follownextPageLink. See Queries.
Keep the id from the create response. For a list you can rely on right away, use /active.
The date parameter of /active
- Send a plain
YYYY-MM-DD. Both ends of the employment are inclusive. - An unparseable
datesilently means today, with200 OK.2026-02-30,15.04.2026, an emptydate=and an un-encoded+all behave so. Validate the date before sending. - An employment with no
info.endDateis returned only up to tomorrow. Do not use/activeto look further ahead. - An employment with no
info.startDatecounts as starting today, so it is never returned for a past date.
Update
POST the employment back with its id. The save replaces the whole object, it is not a patch. Any block you leave out is reset. Read, change, post the complete object:
http
POST /v03/api/employments HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer eyJhbGc...
Content-Type: application/json
{
"id": "EMP123",
"identity": { "firstName": "Pauliina", "lastName": "Palkkanen", "personalId": "190372-942M", "language": "fi" },
"info": {
"workerAccountId": "d7c1f2a4-0000-0000-0000-000000000000",
"type": "monthlySalary",
"pensionCalculation": "employee",
"ibanNumber": "FI3718834100118709",
"taxcard": "auto",
"startDate": "2023-11-15",
"sourceId": "client-emp-4711"
},
"work": { "description": "Chief care of Fifi", "occupationCode": "51640", "wageBasis": "monthly" }
}Posting only the fields to change clears the rest: type, pensionCalculation, taxcard, sourceId, startDate and the whole work block revert. The omitted info also drops info.workerAccountId, so the employment is linked to a new worker record and the old one is left behind. A body with info but without identity fails with 400, unless info.workerAccountId is present.
End an employment
When an employee leaves, end the employment, do not delete it. Ending keeps the history the Incomes Register needs. Set these on info and post the whole object as above:
endDate: the last day of the employment.isTerminated:true.employmentEndingCode: the reason.status:archived.
json
{
"id": "EMP123",
"identity": { "firstName": "Pauliina", "lastName": "Palkkanen", "personalId": "190372-942M", "language": "fi" },
"info": {
"workerAccountId": "d7c1f2a4-0000-0000-0000-000000000000",
"type": "monthlySalary",
"pensionCalculation": "employee",
"taxcard": "auto",
"startDate": "2023-11-15",
"sourceId": "client-emp-4711",
"endDate": "2026-06-30",
"isTerminated": true,
"employmentEndingCode": "jointAgreement",
"status": "archived"
},
"work": { "description": "Chief care of Fifi", "occupationCode": "51640", "wageBasis": "monthly" }
}employmentEndingCode | Reason |
|---|---|
employeesResignation | The employee resigned |
other | Some other reason |
terminationGroundsRelatedToEmployeesPerson | Grounds related to the employee personally |
financialAndProductionRelatedGrounds | Financial or production-related grounds |
jointAgreement | Ended by joint agreement |
retirement | Retirement |
terminationOfaFixedTermEmployment | A fixed term ran out |
Use the name, not the Incomes Register number.
- The reason is reported only when
startDateandendDateare both set along with the code. A code without an end date is stored but not filed. - Set
statustoarchivedyourself. It is not derived fromisTerminated. An employment left atunknownis treated as active, including by the yearly tax card update. - Each calculation takes the code as it was when the calculation was created. Changing the employment later does not change what was already filed; that needs an Incomes Register correction.
- Reversing: post the object with
isTerminated: false,endDate: null,employmentEndingCode: null,status: "primary". This does not retract anything already filed, so do not clear an ending that was already filed. For a genuinely new period, create a new employment: the Incomes Register reports employment periods.
Delete (test only)
DELETE /v03/api/employments/{id} cascades, so use it only in test:
- An unknown
idreturns404. - Any linked calculation, draft or paid, blocks the delete with
400(Työsuhdetta ei voi poistaa). Delete the calculations first. - Linked holiday years and absences are deleted with the employment.
- If it is the worker's only employment, their tax cards and worker record go too.
In test it is usually easier to discard the whole test company than to unwind it employment by employment.
Sync from your own HR data
Treat your system as the master and Salaxy as the place that needs the payroll fields.
- Keep a mapping per employee in your own database: your employee id, the Salaxy employment
idandinfo.workerAccountId. Write it from the create response. - Set
info.sourceIdto your employee id on create. It lets you find the employment again if you lose the mapping. - New employee: look up by
externalIdonly if you have no mapping, allowing for index lag; otherwise create. Send the storedinfo.workerAccountIdwhen the person already has another employment with the company. - Changed data:
GETthe employment, change the fields,POSTthe complete object. - Leaver: end the employment as above. Do not delete.
- Reconcile: compare your active employees with
GET /v03/api/employments/active, not with a list that depends on the index.
For many employees at once there is also POST /v03/api/import/workers, which creates or assures employments in bulk (see Worktime import).
Test it
- Get a test account: Get a test account.
- Create an employment with a temporary test Personal ID and a street address.
- Create a second employment for the same person, sending
info.workerAccountId. Check that the response keeps the same worker id. - End the first employment and read it back:
isTerminated,endDateandstatusshould be as posted.
Checklist
- You store the employment
idandinfo.workerAccountIdfrom every create response. - You always
GET, change andPOSTthe whole employment. You never post a partial body. - You always send
info.startDate,work.occupationCodeand an IBAN, and the street address for temporary Personal IDs. - You end employments with
endDate,isTerminated,employmentEndingCodeandstatus: "archived", not withDELETE. - Your code does not depend on the search index being current right after a write.
Next: Tax cards

