canonical: https://jentic.com/apis/factorialhr.com/factorial # Factorialhr Factorial API Factorial is an HR management platform whose API exposes employee records, attendance shifts, time off, applicant tracking, finance, tasks, and webhook subscriptions across 25 endpoints. The API is dated by version (2026-01-01) and is grouped by tag for ATS, Attendance, Employees, Finance, System, Tasks, Time Off, and Webhooks. It is a single integration point for people-ops automations rather than a narrow point solution. ## For AI agents Manage employees, attendance shifts, time off requests, applications, and HR webhooks across a Factorial workspace. Useful for onboarding, time tracking, and payroll preparation flows. ## Scope Does not handle payroll execution, benefits enrollment, or accounting ledgers - use for HRIS records, attendance, time off, and ATS only. ## Capabilities - Create and update employee records on the workspace - Clock employees in and out and read attendance shift history - Submit and approve time-off leave requests - Track applicants through the ATS application pipeline - Subscribe to webhooks that notify on employee, attendance, and time-off changes - Read finance data attached to employees and contracts - Assign and complete tasks linked to HR workflows ## Use cases ### New Hire Onboarding When a candidate is hired through the Factorial ATS, an automation creates the employee record, opens the relevant attendance schedule, and registers a webhook so payroll and IT systems are notified on employee changes. The flow uses POST `/employees/employees`, the attendance shifts endpoints, and the Webhooks subscription tag. Typical setup runs in minutes once the ATS hand-off is wired. Example prompt: POST the candidate payload to `/employees/employees`, register a webhook on the Webhooks tag for employee.created events, and confirm the new employee id is returned. ### Daily Attendance Sync An attendance integration reads each employee's clock-in and clock-out events at end of day, reconciles them against a scheduling system, and pushes corrections back. The flow centres on `/attendance/shifts` with POST `/attendance/shifts/clock-in` and POST `/attendance/shifts/clock-out` for write paths. Designed for daily batch runs over a workforce of hundreds of employees. Example prompt: List shifts via GET `/attendance/shifts` for the day, post any missing clock-in entries via POST `/attendance/shifts/clock-in`, and reconcile clock-out times against the scheduling system. ### Time-Off Request Workflow An employee submits a leave request through a chat interface; the agent posts the request to Factorial, listens for the approval webhook, and updates the requester. The flow uses POST `/timeoff/leaves` to create the request and a Webhooks subscription to react to the approval state change. Suitable for self-service time-off bots running over Slack or Teams. Example prompt: POST the leave details to `/timeoff/leaves`, register a webhook for leave approval events, and message the employee when the approval status changes. ### Applicant Tracking Pipeline A recruiting agent lists open applications in the ATS, filters by stage, and posts updates as candidates move through interviews. The `/ats/applications` endpoint exposes the application list and downstream operations under the ATS tag handle stage transitions. Suited to recruiters who want a chat agent to summarise pipeline state on demand. Example prompt: Call GET `/ats/applications`, group results by stage, and return a summary of candidates in each stage with the most recent update. ### AI Agent People-Ops Assistant An AI agent embedded in a people-ops workflow uses Jentic to discover Factorial operations and answer questions like 'who is on leave next week' or 'create an employee record for this hire'. Jentic exposes the 25 Factorial operations with their schemas, so the agent does not need to read the developer docs. Designed for HR teams running an internal assistant over Slack. Example prompt: Call jentic.search with 'list employees on leave next week', load the `/timeoff/leaves` operation, execute with a date-range filter, and return the resulting employee names. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/employees/employees` | List all employees | | POST | `/employees/employees` | Create a new employee | | POST | `/attendance/shifts/clock-in` | Clock an employee in | | POST | `/attendance/shifts/clock-out` | Clock an employee out | | POST | `/timeoff/leaves` | Submit a time-off leave request | | GET | `/ats/applications` | List ATS applications | ## Key resources - **Employees** — Create, list, update, and delete employee records on the workspace - **Attendance** — Read shift history and clock employees in and out - **Time Off** — Submit and list leave requests - **ATS** — Track applications through the recruiting pipeline - **Webhooks** — Subscribe to events on employee, attendance, and leave changes ## Why Jentic - **Setup:** Wiring the Factorial API by hand means running its OAuth 2.0 flow, rotating refresh tokens, targeting the dated api.factorialhr.com resources base, and coordinating employees, attendance, and ATS routes yourself. Through Jentic you install once, import the Factorial API from the API Directory, store the OAuth credential once, and your agent calls it. - **Permission scoping:** Factorial's core routes here act on collections with the record details in the request body, so you limit the agent to the operations it needs, such as listing employees, clocking a shift in or out, or submitting a time-off request. You choose those operations, so employee creation or ATS reads are not included unless you add them. - **Credential handling:** Your Factorial OAuth 2.0 credential and refresh token are stored once, encrypted, by your own Jentic One instance and a scoped token is injected at execution time. The client_id, client_secret, and bearer tokens never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'submit a time-off request' or 'clock an employee in', and Jentic returns the matching Factorial operation with its input schema so the agent calls the right endpoint without browsing the developer docs. ## Related APIs - **BambooHR** — US-focused HRIS with employee, time-off, and applicant tracking - **Personio** — European HRIS covering employees, attendance, and recruiting - **Greenhouse** — Dedicated ATS with deeper recruiting workflows - **Workable** — ATS that often feeds candidate data into HRIS systems ## FAQ ### What authentication does the Factorial API use? Factorial uses OAuth 2.0 with the authorization code flow - authorization at https://api.factorialhr.com/oauth/authorize and token exchange at https://api.factorialhr.com/oauth/token. Through Jentic, the OAuth client and refresh tokens are held in the vault and rotated automatically, so the agent only sees a scoped execution permission. ### Can I create an employee record with the Factorial API? Yes. POST the new hire payload to `/employees/employees.` The endpoint returns the created employee id which is used to attach attendance, time-off, and finance records on subsequent calls. ### What are the rate limits for the Factorial API? Rate limits are not declared in the spec. Factorial enforces fair-use throttling on the production tenant - keep batch operations sequential for large workspaces and inspect 429 responses for retry-after hints. ### How do I clock an employee in through Jentic? Run pip install jentic, call jentic.search with 'clock employee in', and execute the returned `/attendance/shifts/clock-in` operation with the employee id and timestamp. Jentic handles the OAuth token exchange so no client credentials enter the agent context. ### Does the Factorial API support webhooks? Yes. The Webhooks tag exposes operations to subscribe to events including employee changes, attendance updates, and time-off approvals. Use these to drive downstream payroll and IT provisioning flows rather than polling the resource endpoints. ### How do I list ATS applications? Call GET `/ats/applications.` The response lists applications across the recruiting pipeline; downstream operations under the ATS tag move candidates between stages or attach notes to an application. ### Can I limit what my agent is allowed to do with the Factorial API? Yes. Because you run Jentic One yourself, you decide which Factorial operations your agent may call, so you can grant only what a given workflow needs, such as listing employees, clocking a shift in or out, or submitting a time-off request. Higher-impact routes like creating an employee record or reading the ATS application pipeline stay out of reach unless you explicitly add them. Your OAuth credential is held by your own instance and a scoped token is injected only at execution time, so the agent never handles the raw client secret or bearer token.