Skip to content

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.

Worker, employment and companyAn employment links a worker, the person, to a customer company, the employer. The employment carries the terms: type, pension, tax card handling and salary defaults. Your own HR data creates and updates the employment with POST /v03/api/employments, and keeps your own employee id in info.sourceId.Workerthe person, bank accountEmploymenttype, pension, tax cardsalary defaultsCustomer companythe employerYour HR datayour employee id = info.sourceIdcreate, update, end
Purple: held by Salaxy. You create and change the employment; Salaxy keeps the worker record behind it.

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:

  1. info.workerAccountId, if your request carries it. This is the reliable route.
  2. Otherwise Salaxy looks the Personal ID up among this company's employments in the search index, and reuses the worker record it finds there.
  3. Otherwise a new worker record is created from identity and the default contact.

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 ​

MethodPathPurpose
POST/v03/api/employmentsCreate (no id in the body) or update (with id). There is no PUT
GET/v03/api/employmentsFind and list. OData query; see Queries
GET/v03/api/employments/{id}Read one full employment
GET/v03/api/employments/active?date=YYYY-MM-DDList 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.type is the employment type: monthlySalary, hourlySalary, salary and so on. A fixed-term employment is marked with info.isFixedTerm, not with a type.
  • info.taxcard is a string: auto, manual, noTaxCard or taxAtSource. See Tax cards.
  • info.pensionCalculation is employee for the standard employee pension.
  • contacts[] entries have a type (default, workerAccount, employerOverride, foreign) and typed fields such as email and telephone.
  • 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.sourceId is your own employee id. It is exposed as the filterable externalId.

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.personalId nor info.workerAccountId is 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-F mean the 2000s, - and U-Y the 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: 310296 fails 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 $top and follow nextPageLink. 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 date silently means today, with 200 OK. 2026-02-30, 15.04.2026, an empty date= and an un-encoded + all behave so. Validate the date before sending.
  • An employment with no info.endDate is returned only up to tomorrow. Do not use /active to look further ahead.
  • An employment with no info.startDate counts 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" }
}
employmentEndingCodeReason
employeesResignationThe employee resigned
otherSome other reason
terminationGroundsRelatedToEmployeesPersonGrounds related to the employee personally
financialAndProductionRelatedGroundsFinancial or production-related grounds
jointAgreementEnded by joint agreement
retirementRetirement
terminationOfaFixedTermEmploymentA fixed term ran out

Use the name, not the Incomes Register number.

  • The reason is reported only when startDate and endDate are both set along with the code. A code without an end date is stored but not filed.
  • Set status to archived yourself. It is not derived from isTerminated. An employment left at unknown is 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 id returns 404.
  • 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.

  1. Keep a mapping per employee in your own database: your employee id, the Salaxy employment id and info.workerAccountId. Write it from the create response.
  2. Set info.sourceId to your employee id on create. It lets you find the employment again if you lose the mapping.
  3. New employee: look up by externalId only if you have no mapping, allowing for index lag; otherwise create. Send the stored info.workerAccountId when the person already has another employment with the company.
  4. Changed data: GET the employment, change the fields, POST the complete object.
  5. Leaver: end the employment as above. Do not delete.
  6. 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 ​

  1. Get a test account: Get a test account.
  2. Create an employment with a temporary test Personal ID and a street address.
  3. Create a second employment for the same person, sending info.workerAccountId. Check that the response keeps the same worker id.
  4. End the first employment and read it back: isTerminated, endDate and status should be as posted.

Checklist ​

  • You store the employment id and info.workerAccountId from every create response.
  • You always GET, change and POST the whole employment. You never post a partial body.
  • You always send info.startDate, work.occupationCode and an IBAN, and the street address for temporary Personal IDs.
  • You end employments with endDate, isTerminated, employmentEndingCode and status: "archived", not with DELETE.
  • Your code does not depend on the search index being current right after a write.

Next: Tax cards

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.