canonical: https://jentic.com/apis/peopleforce.io/peopleforce

# PeopleForce API

The PeopleForce API covers the PeopleForce HR platform's Company API v1: employee records with positions, compensation, salaries, employment statuses, documents, and leave balances, plus leave requests, holidays, assets, teams, tasks, and an in-app recruitment module with vacancies, candidates, and applications. It also exposes HR reports for leave balances and working hours and webhook subscriptions for HR events. PeopleForce marks Company API v1 as deprecated: it no longer receives changes and will stop being supported, so every operation in this spec is flagged deprecated and new integrations should plan to move to a newer Company API version.

## For AI agents

Read and update PeopleForce employee records, compensation, leave requests and balances, assets, teams, tasks, and recruitment pipelines through the deprecated Company API v1.

## Scope

Does not run payroll, process expense claims, or provide the newer Company API versions. Use for PeopleForce employee, leave, asset, and recruitment records through the deprecated Company API v1 only.

## Capabilities

- List employees filtered by hired_on, status, updated_at, or emails[], and create one with first_name, last_name, email, and hired_on
- Terminate an employee with effective_from, termination_type_id, termination_reason_id, eligible_for_rehire, and a comment
- Create leave requests with day-by-day leave_request_entries, list pending ones, and adjust an employee's leave balance
- Record salaries, compensations, positions, and employment statuses on an employee's history
- Assign company assets such as laptops to an employee with issued_on and returned_on dates
- Add candidates, open vacancies, and move an application to a new pipeline_stage_id or disqualify it
- Pull leave balance and working hours reports filtered by department, division, location, or employee

## Use cases

### HR assistant agent through Jentic

An HR assistant agent finds PeopleForce operations through Jentic by intent, for example 'list pending leave requests', and answers questions such as who is off next week or how much leave someone has left from GET `/api/public/v1/leave_requests/pending` and GET `/api/public/v1/employees/{id}/leave_balances.` Jentic injects the X-API-KEY header at call time. Because Company API v1 is deprecated, treat this as a bridge for existing PeopleForce accounts while a newer Company API version is adopted.

Example prompt: Call GET `/api/public/v1/leave_requests/pending`, then for each requester call GET `/api/public/v1/employees/{id}/leave_balances` and summarise who has enough balance

### Leave booking

POST `/api/public/v1/leave_requests` books time off and requires employee_id, leave_type_id, starts_on, ends_on, a description, a leave_request_entries list with occurs_on and amount for each day, and skip_approval. GET `/api/public/v1/leave_requests` filters by state, employee, and date window to confirm the result.

Example prompt: POST `/api/public/v1/leave_requests` with employee_id, leave_type_id for vacation, starts_on '2026-11-16', ends_on '2026-11-18', description 'Family trip', leave_request_entries for each of the three days with amount '1', and skip_approval 'false'

### Employee lifecycle records

New hires are created with POST `/api/public/v1/employees`, history entries go through the positions, salaries, compensations, and employment_statuses sub-resources under `/employees/{employee_id}`, and leavers are processed with POST `/api/public/v1/employees/{id}/terminate`, which requires effective_from, termination_type_id, termination_reason_id, eligible_for_rehire, and a comment. Asset assignments track equipment handed to each person.

Example prompt: POST `/api/public/v1/employees` with first_name 'Ana', last_name 'Silva', email 'ana@example.com', and hired_on '2026-12-01', then POST `/api/public/v1/asset_assignments` with her user_id, the laptop asset_id, and issued_on '2026-12-01'

### In-app recruitment pipeline

PeopleForce's recruitment module is exposed under `/api/public/v1/recruitment`: create candidates with full_name and email, list vacancies and their applications, and advance an application with PUT `/api/public/v1/recruitment/vacancies/{vacancy_id}/applications/{id}/move` and a pipeline_stage_id, or disqualify it with a reason.

Example prompt: List GET `/api/public/v1/recruitment/vacancies/{vacancy_id}/applications`, then PUT `/api/public/v1/recruitment/vacancies/{vacancy_id}/applications/{id}/move` with pipeline_stage_id for the interview stage

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/public/v1/employees` | List employees (deprecated v1) |
| POST | `/api/public/v1/employees` | Create an employee (deprecated v1) |
| POST | `/api/public/v1/employees/{id}/terminate` | Terminate an employee (deprecated v1) |
| POST | `/api/public/v1/leave_requests` | Create a leave request (deprecated v1) |
| GET | `/api/public/v1/leave_requests/pending` | List pending leave requests (deprecated v1) |
| GET | `/api/public/v1/reports/hr/leave_balances` | Leave balances report (deprecated v1) |
| PUT | `/api/public/v1/recruitment/vacancies/{vacancy_id}/applications/{id}/move` | Move an application to a pipeline stage (deprecated v1) |

## Key resources

- **Employees** — Employee records with positions, salaries, compensations, employment statuses, documents, assets, leave balances, activation, and termination
- **Leave** — Leave requests, pending approvals, leave types, holiday policies, and holidays
- **Assets** — Assets, asset categories, and assignments to employees
- **Organisation** — Departments, divisions, locations, positions, teams, job profiles, and employment types
- **Recruitment** — Vacancies, candidates, applications, pipelines, sources, and disqualify reasons
- **Reports and webhooks** — Leave balance and working hours reports, and webhook subscriptions

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 49 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 98 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 29 / 100
  - Agent Usability: 61 / 100
  - Security: 50 / 100
  - AI Discoverability: 56 / 100
- **View full report:** https://jentic.com/apis/peopleforce.io/peopleforce/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring PeopleForce by hand means getting a Company API key with the right permissions granted, sending it in the X-API-KEY header, encoding form-urlencoded request bodies, and paging list results yourself. Through Jentic you install once, import PeopleForce from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** PeopleForce puts the employee id and vacancy id in the URL path (`/api/public/v1/employees/{id}/...` and `/recruitment/vacancies/{vacancy_id}/...`), so a rule can pin your agent to one employee's records or one vacancy's applications. You choose the operations it may call, so destructive ones like terminating an employee or deleting salaries are not included unless you add them.
- **Credential handling:** Your PeopleForce API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list pending leave requests' or 'create an employee', and Jentic returns the matching PeopleForce operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **BambooHR API** — HRIS for employee records, time off, and reports
- **Bob API** — HiBob HR platform for people data, time off, and lifecycle
- **Personio API** — HR platform for employees, absences, and attendance in Europe
- **Workable API** — Dedicated applicant tracking for jobs and candidates

## FAQ

### Is the PeopleForce Company API v1 deprecated?

Yes. The spec states that Company API v1 no longer receives changes and will stop being supported, and every operation in it is marked deprecated. It still describes the endpoints existing PeopleForce integrations call, but plan to move to a newer version of the Company API.

### What authentication does the PeopleForce API use?

Per its OpenAPI spec, the PeopleForce API takes a Company API key in the `X-API-KEY` header. The spec notes that Service account keys and Career keys are refused with 401, and that each of a new key's four permissions defaults to None, so calls return 403 until permissions are granted. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time.

### How do I list pending leave requests through Jentic?

Search Jentic for 'list pending leave requests in PeopleForce', load the schema for GET `/api/public/v1/leave_requests/pending`, and page through the results with the page parameter. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### What are the rate limits for the PeopleForce API?

The OpenAPI spec does not specify rate limits. Check https://help.peopleforce.io for current limits.

### Is there a PeopleForce MCP server?

You don't need an MCP server to give your agent the PeopleForce API. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it. Operations are discovered on demand, so no extra tool definitions sit in the agent's context.

### Can I limit what my agent is allowed to do with the PeopleForce API?

Yes. For example, write a rule that allows only GET `/api/public/v1/leave_requests/pending`, GET `/api/public/v1/employees/{id}/leave_balances`, and GET `/api/public/v1/reports/hr/leave_balances`, so a leave assistant can answer balance questions but cannot terminate employees, change salaries, or delete records. Every call it makes is logged by your Jentic One instance.