Skip to content

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 ​

MethodEndpointDoes
POST/v03/api/employmentsCreates 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 }
    ]
  }
}
FieldWhy it matters
info.taxcard: "auto"The tax card is fetched automatically from the Tax Administration
work.occupationCodeRequired for Incomes Register reporting — a code from Statistics Finland's classification of occupations (here 51640, animal carers)
work.descriptionShown on the salary slip
work.salaryDefaultsRows every calculation for this employment starts with — a salary, or recurring items such as a phone benefit
info.sourceIdYour own id for the employment
work.wageBasis, work.monthlyHoursOptional. 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/employments returns the employment with its id.
  • You stored info.workerAccountId for 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.

← 2. Authenticate · 4. Create a payroll →

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.