ERP employee directory integration
Endpoints for pushing org structure and employee data into PeopleForce from an ERP.
This guide covers the endpoints useful for pushing data into PeopleForce from an external ERP: how to set up your structural lists, create employee records, and keep them up to date. It's a starting point — for anything not covered, browse the API reference in the sidebar.
Prerequisite: an API key. If you don't have one, start with Authentication.
Step 1. Prepare your structural lists
Before creating employees, set up the org data their profiles reference. Create these in the PeopleForce UI or via the API.
| Resource | Endpoint | Notes |
|---|---|---|
| Locations | POST /locations | Your offices or places of operation. |
| Divisions | POST /divisions | Larger business units. |
| Departments | POST /departments | Main structural units; can be nested — create parents first, then pass the parent ID. |
| Employment types | POST /employment_types | Full-time, part-time, contractor, etc. |
| Positions | POST /positions | Titles assigned to employees. |
Already have these lists? Use the matching GET endpoints to fetch their IDs
(which you'll need when creating employees), and the PUT endpoints to update
them.
Step 2. Create employees
Create the employee record
Create an employee with POST /employees — see
Adding a new hire from another ATS for the request shape.
Fetch existing employees with GET /employees and update with
PUT /employees/{id}.
Add an employment status
POST /employees/{id}/employment_statuses records work schedule, employment
type, probation, and effective date. Add a new record for each change to
preserve history.
Add a position
POST /employees/{id}/positions records the employee's position, department,
division, location, and manager. Add a new record for each change (e.g. a
promotion).
Add compensation
POST /employees/{id}/salary records salary, frequency, currency, and effective
date. Add a new record for each change.
Step 3. Leave balances
Receiving leave balances from an external system is disabled by default for security and enabled per request — contact us to set it up. The flow involves creating leave types and policies and assigning policies to employees; you can also subscribe to leave-request webhooks to react to changes.