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 or similar system: how to set up your structural lists, create people records, and keep them up to date. It's a starting point, not exhaustive — for anything not covered, see the API reference.

Prerequisite: an API key. If you don't have one, start with Authentication.

Coverage note. v4 is under active development and exposes a curated subset of endpoints today. Several resources the original guide used (standalone locations, employee position-history and employment-status records, salary create, and leave) exist in the v4 roadmap but are not yet mounted in the live API. Where v4 has a live equivalent it's used below; the rest are flagged as not-yet-available. Always check the API reference for the currently available endpoints.

Renamed, not removed. v4 job_titles is the same catalog as the old positions, and v4 work_types is the same as the old employment_types — identical records and IDs, just renamed endpoints. (Note the name reuse: /people/:id/positions is a different, employee-scoped concept — a person's dated position-history record — and is not yet mounted.)

Step 1. Prepare your structural lists

Before creating people, set up the org data their profiles reference. You can create these in the PeopleForce UI or via the API.

Resource	v4 endpoint	Notes
Divisions	`POST /api/v4/divisions`	Your larger business units.
Departments	`POST /api/v4/departments`	Main structural units; can be nested — create parents first, then pass the parent ID when creating children.
Job titles	`POST /api/v4/job_titles`	Catalog of titles assigned to people. Renamed from the old `positions` (same records and IDs).
Work types	`POST /api/v4/work_types`	Terms of cooperation (e.g. full-time, contractor). Renamed from the old `employment_types` (same records and IDs).
Locations	—	Not yet mounted in v4. The old guide used `POST /locations`.

Already have these lists? Use the matching GET endpoints (e.g. GET /api/v4/divisions, GET /api/v4/departments) to fetch their IDs, which you'll need when creating people. Update items with the PUT endpoints (e.g. PUT /api/v4/departments/{id}).

Step 2. Create people

Create the person record

Create a person with POST /api/v4/people — see Adding a new hire from another ATS for the request shape and the note on which fields v4 accepts at create time.

Fetch existing people with GET /api/v4/people, a single person with GET /api/v4/people/{id}, and update with PUT /api/v4/people/{id}.

Salary

You can read and update existing salary records under /api/v4/people/{person_id}/compensation/salaries — GET to list, GET /{id}, PUT /{id} to update, and DELETE /{id}.

Creating a salary isn't available on the live v4 surface yet (the mounted salaries endpoint exposes list/show/update/delete only). To preserve history, the intended model is a new record per change — but until the create endpoint is mounted, set initial salary in the PeopleForce UI.

Employment status and position-history records (employment_statuses and the employee-scoped positions in the old API) are part of the v4 roadmap but not yet mounted. They model how v4 keeps employment-status and position history (possibly via people/{id}/lifecycles).

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 overall flow involves creating leave types and policies and assigning policies to people; you can also subscribe to leave-request webhooks to react to changes.

Leave types, policies, and balances are not in the Company API v4 surface documented here. This step is preserved from the original guide pending v4 coverage.