canonical: https://jentic.com/apis/apiv3.factorialhr.com/factorialhr

# Apiv3 Factorialhr Factorial HR API

Jentic publishes the only available OpenAPI specification for Factorial HR API, keeping it validated and agent-ready. Factorial is a European HR platform used by SMEs to manage employees, teams, time off, attendance shifts, payroll supplements, and HR documents. The 2024-10-01 API surface gives programmatic access to the core HR record (employees, teams), the request flows for time off and attendance, and document storage, so integrators can sync HR data into IT, finance, or recruitment workflows. Authentication uses a bearer token issued from the Factorial workspace settings.

## For AI agents

Manage Factorial HR employees, teams, time-off requests, attendance shifts, payroll supplements, and HR documents through a versioned API.

## Scope

Does not handle running payroll itself, ATS recruiting pipelines, or employee performance reviews - use for HR records, time off, attendance, and payroll supplements only.

## Capabilities

- List, create, update, and delete employee records under /resources/core/employees
- Manage teams and their membership through /resources/core/teams
- Submit and approve time-off leave requests via /resources/time_off/leaves
- Record and update attendance shifts via /resources/attendance/shifts
- Create payroll supplements that feed Factorial's payroll cycle
- Read and store HR documents tied to employee records

## Use cases

### HRIS Synchronisation

Engineering and IT teams sync Factorial employees into Okta, Jira, and Slack so that joiners get the right access on day one and leavers are deprovisioned automatically. GET /resources/core/employees lists the workforce and the team endpoints expose reporting structure, so a downstream IAM platform can mirror the HR record without manual exports.

Example prompt: List employees via GET /resources/core/employees, diff against the IAM directory, and create or deprovision accounts based on the result.

### Time-off Request Automation

Operations teams replace email-based holiday requests with a Slack or Microsoft Teams flow that creates a leave directly in Factorial. POST /resources/time_off/leaves submits the request and GET /resources/time_off/leaves/{id} polls for approval, while GET /resources/time_off/policies surfaces the available leave types so the form stays in sync with HR policy.

Example prompt: Create a leave request via POST /resources/time_off/leaves with the employee ID, start date, end date, and policy, then notify the manager.

### Payroll Supplement Feed

Finance teams running monthly bonuses, commissions, or expense reimbursements push them into Factorial as payroll supplements rather than emailing spreadsheets. POST /resources/payroll/supplements adds the line item against an employee and GET /resources/payroll/supplements lists what is queued for the next payroll run, giving finance an auditable trail.

Example prompt: Create payroll supplements for the sales team's monthly commission via POST /resources/payroll/supplements with the employee ID, amount, and label.

### AI Agent HR Assistant

An AI agent acting as an HR copilot can use Jentic to answer 'who is on leave next week' or 'create a leave request for me' without managing the Factorial bearer token directly. Jentic returns the matching operation by intent search, validates inputs against the schema, and isolates credentials so the agent never sees the raw token.

Example prompt: Search Jentic for 'submit a time-off request', load the POST /resources/time_off/leaves schema, and execute it using the requesting employee's ID and date range.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /resources/core/me | Get the current authenticated user. |
| GET | /resources/core/employees | List employees in the workspace. |
| POST | /resources/core/employees | Create a new employee record. |
| POST | /resources/time_off/leaves | Submit a time-off leave request. |
| GET | /resources/time_off/policies | List the configured time-off policies. |
| POST | /resources/attendance/shifts | Record an attendance shift for an employee. |
| POST | /resources/payroll/supplements | Add a payroll supplement to the next payroll run. |
| GET | /resources/documents/documents | List HR documents. |

## Key resources

- **Employees** — List, create, fetch, update, and delete employee records under the core HR namespace.
- **Teams** — Manage teams and their membership; create new teams or update structure.
- **Time Off** — Submit, retrieve, update, and delete leave requests; list available time-off policies.
- **Attendance** — Record, retrieve, update, and delete attendance shifts for employees.
- **Payroll** — List and create payroll supplements that feed the next payroll run.
- **Documents** — List HR documents associated with an employee.

## Why Jentic

- **Setup:** Wiring Factorial HR by hand means learning its bearer auth and mapping across its core, time-off, attendance, payroll, and documents resource families yourself. Through Jentic you install once, import the Factorial HR API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** You choose which Factorial operations the agent may call, so you can limit it to the ones it needs, such as reading employees and submitting time-off leaves, while leaving out writes like creating employees or posting payroll supplements. The rule is a positive allow-list, so the agent only runs the operations you have added.
- **Credential handling:** Your Factorial bearer token 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 'submit a time-off request' or 'list employees', and Jentic returns the matching Factorial operation with its input schema so the agent calls the right endpoint without reading the Factorial docs site.

## Related APIs

- **BambooHR API** — US-focused HRIS covering employees, time off, and reports - same shape, different geography.
- **Gusto API** — US payroll-first HR platform that complements employee records with full payroll execution.
- **Rippling API** — Unified HR + IT + finance platform with deeper IT provisioning than Factorial.
- **HiBob API** — European-friendly HRIS with rich people analytics and similar API coverage.

## FAQ

### Why is there no official OpenAPI spec for Factorial HR API?

Factorial does not publish an OpenAPI specification - its developer reference is rendered as HTML at apidoc.factorialhr.com. Jentic generates and maintains this spec so that AI agents and developers can call Factorial HR API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Factorial HR API use?

Factorial uses HTTP Bearer authentication. Generate an API token from the workspace settings and pass it as Authorization: Bearer <token> on every call. Through Jentic the token is stored encrypted in the vault and injected at call time, so it never enters the agent's prompt context.

### Can I run payroll itself with this API?

Not directly. The payroll surface in this version exposes /resources/payroll/supplements only - you can add bonuses, commissions, and other supplements that feed the next payroll cycle, but the actual payroll run is triggered inside the Factorial workspace by a payroll administrator.

### What are the rate limits for the Factorial HR API?

Factorial does not document a numeric rate limit in the spec; limits are applied per workspace and surfaced via 429 responses when exceeded. Treat batch operations (e.g. employee list + per-employee document fetches) as paginated and back off on 429.

### How do I create a time-off request through Jentic?

Run pip install jentic, then search Jentic for 'submit a time-off request', load the schema for POST /resources/time_off/leaves, and execute it with the employee ID, start_on, end_on, and the policy. Jentic injects the bearer token from your stored Factorial credentials. Run it through Jentic One, the self-hosted execution layer.

### Does the API expose the employee directory in real time?

Yes. GET /resources/core/employees returns the live employee directory and GET /resources/core/employees/{id} fetches a single record. Pair the list call with GET /resources/core/teams to recover reporting structure for downstream IAM or directory sync.

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

Yes. Because you run Jentic One yourself, your own rules decide which Factorial operations and credentials the agent may use, working as a positive allow-list so it can only call the operations you have added. You can restrict it to read-only work like listing employees via GET /resources/core/employees and submitting leave via POST /resources/time_off/leaves, while leaving out writes such as creating employee records or posting payroll supplements. Any operation you have not added stays off limits to the agent.