Employee management integrations

Managing employees across Planday and other systems is a key use case and linked to a variety of systems like HR, payroll, communication and e-learning.

Use the basic actions to create, read or update (and deactivate) employees. The GET employees endpoint is a list endpoint that returns all active employees with basic data. The GET employees by ID endpoint returns more detailed information about the employees - including custom fields.

Special fields

Some employee fields require some extra attention. We call these special fields. To manage the special fields for both read, create and update actions you have to add the dedicated scopes to you API application as well as including the fields in the URL as path parameters.

Special fields:

• Ssn (Social security number)
• BankAccount
• BirthDate

Custom fields

In Planday, managers can create new employee fields if they want something specific to be shown for each employee. These fields are what we call custom fields.

Custom fields are created with a certain type that gives information about the data which can be inputted into the field. The supported types are:

• in text form
• in numeric form
• as an enabled or disabled state
• as a calendar date
• as an uploaded picture

Employee custom fields are returned in the GET employee by Id endpoint.

Create or update custom field values on an employee

You can also specify a custom field value when creating or updating an employee. For this you will need to follow the steps below:

1. Query the GET Employee field definitions endpoint to get a list of all the possible custom fields on the specific portal. All custom fields is listed as “custom_xxxx” in the properties collection, where “xxxx” is a number.

2. When creating/updating an employee, use the custom field id ("custom_xxxx") as key of the field you want to update.

The create and update requests differ in how the username is handled, so they use slightly different bodies.

Create — the username is the employee's login. On most portals the username and email are the same value, so you can supply userName, email or both, and the value is used as both the username and the email; if you supply both they must be the same valid email address. On legacy portals that keep username and email separate, userName is required and email is optional. To create a draft employee, leave out both, see Draft employees below.

{
 "firstName": "First",
 "lastName": "Last",
 "userName": "x-planday123123@planday.com",
 "cellPhone": "1234567",
 "street1": "Example",
 "zip": "12332",
 "city": "ExampleCity",
 "phone": "23213232",
 "gender": "Female",
 "email": "x-planday123123@planday.com",
 "departments": [147991],
 "employeeGroups": [266955],
 "custom_146688": true,
 "custom_164605": 5
}

Update — userName is not accepted here, and on most portals email is ignored because it is part of the login. The login (username and email) is changed through the dedicated Change username endpoint. On legacy portals that keep username and email separate, email can still be updated here.

{
 "firstName": "First",
 "lastName": "Last",
 "cellPhone": "1234567",
 "street1": "Example",
 "zip": "12332",
 "city": "ExampleCity",
 "phone": "23213232",
 "gender": "Female",
 "departments": [147991],
 "employeeGroups": [266955],
 "custom_146688": true,
 "custom_164605": 5
}

Draft employees

A draft employee is an employee created without an email, for example when the email is not known yet. To create one, leave out both userName and email when creating the employee. Fields that are required on the portal are still required.

{
 "firstName": "First",
 "lastName": "Last",
 "departments": [147991]
}

email and userName are not returned for draft employees. To invite a draft employee, provide their email in the request body of the Invite employee endpoint. It is set as their username and email before the invitation is sent. If the email is left out for a draft employee, no invitation is sent. Do not provide an email when inviting other employees.

{
 "email": "first.last@example.com"
}

Updating employees’ pay rates and contract rules

Pay rates and salaries

You can add pay rates and salaries to employees in Planday by using the Pay API (Please note that rates are linked to employee groups in Planday). The API also supports other related functionality like read rate history for an employee, read and update monthly salaries and allocation of the cost in schedule. Use the PUT /pay/v{version}/payrates/employeeGroups/{employeeGroupId} to specify an employee’s pay rate in a given employee group or the PUT /pay/v{version}/salaries/employees/{employeeId} to specify a salaried employee’s salary.

Salary codes

When managing the rates and salaries, you should also consider to handle the salary codes, which are used to identify pay items for payroll, in your requests. If the salary codes are added by managers inside Planday, you should start your update operations by fetching the existing values and use them when making the update request.

Contracted hours

The Contract Rules API makes it possible to read the contract rules created in Planday and assign them to employees. A contract rule defines an employee’s contracted hours per week, month or year. The intervals are set up in Planday settings. Use the PUT /contractrules/v{version}/employees/{employeeId} to update an employee with a given contract rule.