Appearance
3. Create employees
In the API, an employee is an employment relationship — employment for short: one worker and one employer, carrying the payroll terms. See Core concepts.
Examples use the test environment (test-secure.salaxy.com); see Environments for demo and production.
The endpoint
| Method | Endpoint | Does |
|---|---|---|
POST | /v03/api/employments | Creates the employment — and the worker record, if the person is new |
The request
json
{
"identity": {
"firstName": "Pauliina",
"lastName": "Palkkanen",
"personalId": "190372-942M",
"language": "fi"
},
"contacts": [
{
"type": "default",
"street": "Ansionkatu 1",
"postalCode": "01337",
"city": "PALKKALA",
"email": "pauliina.palkkanen@example.com",
"telephone": "+358401234567890"
}
],
"info": {
"type": "monthlySalary",
"pensionCalculation": "employee",
"pensionRule": "default",
"ibanNumber": "FI3718834100118709",
"taxcard": "auto",
"startDate": "2023-11-15",
"sourceId": "ID98765432"
},
"work": {
"description": "Chief care of Fifi",
"occupationCode": "51640",
"wageBasis": "monthly",
"monthlyHours": 160,
"salaryDefaults": [
{ "rowType": "monthlySalary", "count": 1, "price": 3000 },
{ "rowType": "phoneBenefit", "count": 1, "price": 20 }
]
}
}| Field | Why it matters |
|---|---|
info.taxcard: "auto" | The tax card is fetched automatically from the Tax Administration |
work.occupationCode | Required for Incomes Register reporting — a code from Statistics Finland's classification of occupations (here 51640, animal carers) |
work.description | Shown on the salary slip |
work.salaryDefaults | Rows every calculation for this employment starts with — a salary, or recurring items such as a phone benefit |
info.sourceId | Your own id for the employment |
work.wageBasis, work.monthlyHours | Optional. wageBasis follows info.type, and monthlyHours the company's default; give them only when the default does not fit |
Temporary identity codes need an address
The sample's identity code, 190372-942M, has an individual number of 900 or more — a temporary identity code. For those, the worker's street, postal code and city are required before a calculation validates. The employment is created either way, so leaving the address out fails later, not here.
After the call
The response is the saved employment, trimmed here:
json
{
"id": "<employment id>",
"info": {
"workerAccountId": "<worker account id>",
"startDate": "2023-11-15"
}
}Store info.workerAccountId from the response. It identifies the worker record Salaxy created for this person. Send it back on any further employment for the same person — otherwise you get a duplicate worker record.
Save for the next step
id— the employment, to build the calculation from in step 4.info.workerAccountId— the worker, for the calculation and for any further employment of the same person.
Check
POST /v03/api/employmentsreturns the employment with itsid.- You stored
info.workerAccountIdfor the next employment of the same person. - The employment has an occupation code — and, for a temporary identity code, a street address.
- Searching by your own id finds it:
$filter=externalId eq '<your sourceId>'.
Runnable sample
The interactive version of this step — sign in and run it against your test account — is on the current developer site: create employees. The runnable samples stay there; the steps and endpoints are here.

