How to add and administrate employees through the Personnel Ticket API
Overview
This guide explains how to add and manage employees through the Personnel Ticket API. It is intended for partners who want to integrate their own HR or employee management systems with the personnel ticket system.
The personnel ticket system determines employee eligibility for personnel ticket rights based on registered employee data. The data you import through the API is used to automatically manage ticket rights for employees, so it is important to keep the information up to date.
Employee data is handled in two stages:
1. Import stage: When you import employee data via the API, an employee import record is created. This represents the data you have submitted, but it is not yet active in the personnel ticket system.
2. Processing stage: A scheduled background job processes employee imports and transfers them to the main employee register. Once processed, the employee becomes an active employee and is used for ticket eligibility and other operations. The background job runs every 10 minutes, so there may be a delay between importing an employee and it being available in the system.
Because of this asynchronous flow, changes are not applied immediately. After creating or updating an employee import, it may take a few minutes before the employee appears in the system and can be used in other API operations.
The Employee Import API allows you to
1. Import a new employee
Create an employee import record to submit a new employee to the system.
Use the Employee Import API to send the employee data. The response includes an ID that identifies the import record. This ID may be used for updating or retrieving the import before it has been processed.
2. Import multiple employees using CSV
You can import multiple employees in a single request by uploading a CSV file.
Each employee in the response will include an ID identifying its import record, which can be used for follow-up operations.
For details on the CSV format and request structure, see: Import employees via CSV
3. Update an imported employee
You can update an employee before it has been processed by modifying its import record.
Use the importedEmployeeId (the import ID returned during creation) to update the data.
4. Retrieve an imported employee
You can retrieve the data of an imported employee record using its import ID.
5. Retrieve an employee
To retrieve an employee in the employee registry, you need to search using the national identification number.
You may also search by employeeNo, but this is not guaranteed by the system to be unique within an organisation.
If successful, the response will include the internal employee ID.
This ID can be used for follow-up operations such as setting the yearly fee status or registering disability proof status.
6. Set the yearly fee status for an employee
Once an employee has been processed and is available in the employee registry, you can set the yearly fee status.
This operation uses the internal employee ID (not the import ID).
7. Register disability proof status for an employee
You can register disability proof status for an employee for a given year.
This operation also requires the internal employee ID (not the import ID).
Next steps
Guide: How to Connect Profiles with Personnel Ticket Rights