Apiv3 Factorialhr Factorial HR API
★ Only Publicly Available OpenAPI DocumentHR recruitingEmployee Managementbearer30 EndpointsREST
For Agents
Manage Factorial HR employees, teams, time-off requests, attendance shifts, payroll supplements, and HR documents through a versioned API.
Use for: List all employees in the Factorial workspace, Create a new Factorial employee record, Submit a time-off request for an employee, Get the current authenticated Factorial user
Not supported: Does not handle running payroll itself, ATS recruiting pipelines, or employee performance reviews - use for HR records, time off, attendance, and payroll supplements only.
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.
Install Jentic One Beta
Connect the Factorial HR API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Factorial HR API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fapiv3.factorialhr.com%2Ffactorialhr" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fapiv3.factorialhr.com%2Ffactorialhr" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Factorial HR API.
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
Patterns agents use Factorial HR API for, with concrete tasks.
★ 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.
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.
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.
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.
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
30 endpoints — jentic publishes the only available openapi specification for factorial hr api, keeping it validated and agent-ready.
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.
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.
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Factorial HR API through Jentic.
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.
GET STARTED