ERP employee directory integration

Preconditions: you have generated API key.
If not, we suggest you start with API authentication

This article is looking at endpoints that might be useful for companies that are looking to push data into PeopleForce from an external ERP or another solution. This articles covers all the key aspects you might need, but is not extensive. If something you are looking for is not listed here check API reference. Here is explained on how to create lists, retrieve them and keep them updated, as well as how create employee records and keep those up-to-date.

Step 1. Preparing your lists: divisions, departments and others

Before proceeding with the creation of employees, you must create the main data that will be used to fill in the profiles. They can be created manually from the system or via the API.

It is far more convenient to create custom fields and work schedules from the PeopleForce interface. So you can create them only via the Web interface.

1. Create your locations

Create a location. It could be your offices or the places your company operates in.

2. Create your division

Create a division. Divisions are usually your bigger business units.

3. Create your departments

Create a department. Departments are the main structural units of your company. They can be nested, so a department can be split into multiple subdepartments, and a subdepartment can be split to have children departments as well.

Start by creating parent departments and when you are ready with them you can create child departments for them. You will need to pass the ID of the part department with the creation of the child to create an association.

4. Create your employment types

Create an employment type. Full-timers, part-timers or any other terms of cooperation in your company can be created with this endpoint.

5. Create your positions

Create a position. All the positions, that later will be assigned to your employees.

What if I have previously created all the needed lists?

No worries, we've got you covered!
Use the following methods and receive the ids of your list items. You will need them for creating and updating employee records.

What if I need to update created items?

Use the following PUT methods with the id of the item you want to update.
Update a division and Update a department.

Step 2. Creating employee profiles

It's time for the creation of a database of your employees with the fields containing personal information, as well as employment records. After creating a profile, in order to display data on the position, compensation and employment, and especially the chronology of changes, you must additionally push this data via specific endpoints.

1. Create an employee profile

Create an employee. Employee profiles are accounts that your employees will be using to log in to the system. You can store all the main information about the employee in their profile. This covers
first and last name, date of birth, email, phone number, etc. If you didn't find a field you would like to, you can always create one in the Settings → Employee fields.
To reference a custom employee field when using API you will need to use field UUID. You can find it when you click edit on the field after you created it. You will find how to use the field in endpoint documentation.

What if I have previously created all the employees?

That's fine! You can retrieve all the employees by Get all employees

To receive information about a particular employee use Get an employee , Get all employee fields

What if I need to update created employees?

To update use Update an employee

2. Create an employment status

Create an employee employment statuses. Here you should add a record of work schedule, employment type, probation period, and effective from date.
We recommend you create a new record for every change that happens for the employee. For example, if the employee was promoted from part-time to full-time, we suggest you push a new record effective from the date as the changes take effect in your company.

To receive information about employment status use Get employment status

To update information about employment status use Put employment status

3. Create an employee position

Create an employee position. You can add information about what position employee has, which department, division, and location they work in and who is their manager. We recommend you create a new record for every change that happens for the employee. For example, if the employee was promoted from Middle front-end developer to Senior front-end developer, we suggest you push a new record effective from the date as the changes take effect in your company.

To receive information about employee position use Get employee position

To update information about employee position use Put employee position

4. Create an employee compensation

Create of employee compensations. You can add information about what salary employee has, how often they are paid, in what currency and when it's effective. We recommend you create a new record for every change that happens for the employee. For example, if the employee received a pay rise, we suggest you push a new record effective from the date as the changes take effect in your company.

To receive information about employee compensation use Get employee compensation

To update information about employee position use Put employee compensation

Step 3. Updating vacation, sick leave and other leave balances

You will need to contact us to get your PeopleForce set up for receiving balances from an external system. This is disabled by default for security reasons and can be enabled per request. This step of integration might be tricky and depends on your business needs, so we suggest you reach out to us and we will guide you.

The overall integration of leave balances will have 3 main steps:

Creating leave types.
Creating leave policies.
Assigning policies to employees.
Additionally, you can set up some webhooks to receive an event when any leave request was created so you can update the balance, or pull the list of requests from API.

We recommend using default tools that PeopleForce provides for tracking leave balances and requests, but we understand the needs of different businesses, so we made this option possible.