ERP employee directory integration
Quick guide of our endpoints that you might need for integration
Preconditions: you have generated API key.
If not, we suggest you start with API authentication
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.
- List all locations
- List all divisions
- List all departments
- List all employment types
- List all positions
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.
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.
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.
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.
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.
Updated 15 days ago