# 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](https://code.salaxy.com/get-started/rest/create-employees.md).

Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. Authenticate as the **employer** (the customer company): see [Impersonation](https://code.salaxy.com/security/impersonation.md).

*Diagram: An 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. (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

| 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](https://code.salaxy.com/reference/queries.md) |
| `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](https://code.salaxy.com/get-started/rest/create-employees.md). 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](https://code.salaxy.com/integration/tax-cards.md).
- `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](https://code.salaxy.com/integration/company-settings.md).

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

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" }
}
```

| `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 `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](https://code.salaxy.com/integration/worktime-import.md)).

## Test it

1. Get a test account: [Get a test account](https://code.salaxy.com/get-started/test-account.md).
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](https://code.salaxy.com/integration/tax-cards.md)
