Welcome to development with Factorial!
This page will help you get started with Factorial. You'll be up and running in a jiffy!
Welcome to our API documentation. We are glad you are here, and we are looking forward to what you build.
This page is the shortest route from "I have an account" to "I made my first API call", plus a map of where everything else lives.
What you can build
The public API covers the HR record and the processes around it:
| Area | Typical integration |
|---|---|
| Employees & organisation | Keep a roster in sync; provision and deprovision access automatically. |
| Time tracking & attendance | Push clock-ins from terminals, mobile apps or access control; pull corrections back. |
| Time off & absences | Read approved leave and feed downstream scheduling or payroll. |
| Payroll & compensation | Export worked time and variables; bring payroll results back in. |
| Recruitment (ATS) | Create candidates and applications, and move them through hiring phases. |
| Finance | Expenses and cost data. |
Browse everything endpoint by endpoint in the API Reference.
Pick your path
How you authenticate depends on who the integration is for. Decide this first — it shapes your whole setup.
Building for your own companyAn internal tool, script or one-off sync for a single Factorial account.
You can start today: generate an API Key from company settings, or use OAuth 2.0 if you need finer access control. No registration, no approval queue.
Start with Authentication methods, then the API Keys Setup Guide.
Building for other companiesA marketplace integration or partner product that many Factorial customers will connect to.
OAuth 2.0 is required. You will register an OAuth application, agree the scopes you need, and receive credentials.
Start with the Partner guide — Company token, then OAuth Scopes.
Four things to know before your first call
1. Pick the right environment. Production and demo are separate clusters with separate credentials. Sending production credentials to the demo host returns empty responses rather than an error.
| Environment | API base URL |
|---|---|
| Production | api.factorialhr.com |
| Demo | api.eu2.demo.factorial.dev |
2. The version lives in the path. Every request names the API version it expects: /api/2026-10-01/resources/.... Pin it explicitly and migrate deliberately — see API versioning.
3. The auth header depends on your credential. An API Key goes in x-api-key. An OAuth token goes in Authorization: Bearer.
4. Lists are paginated. Every list endpoint returns at most 100 records, whether or not you ask. See Pagination.
Your first API call
The quickest way to prove a credential works is to ask the API who it belongs to. This endpoint returns the identity behind the token or key you just sent.
With an OAuth token
curl --request GET \
--url 'https://api.factorialhr.com/api/2026-10-01/resources/api_public/credentials' \
--header 'accept: application/json' \
--header 'Authorization: Bearer <access_token>'With an API Key
curl --request GET \
--url 'https://api.factorialhr.com/api/2026-10-01/resources/api_public/credentials' \
--header 'accept: application/json' \
--header 'x-api-key: <api_key>'If you are working against the demo environment, swap the host for api.eu2.demo.factorial.dev.
Two things that catch people outThe header is
Authorization, notAuthentication. And a200with an empty body usually means the credential belongs to the other environment.
Core concepts
| Concept | Why it matters on day one | Guide |
|---|---|---|
| Environments | Credentials are not shared between production and demo. | Environments |
| Versioning | Versions are supported for one year; an expired one does not fail loudly. | API versioning |
| Authentication | An API Key grants everything; OAuth lets you scope access. | Authentication |
| Webhooks | Get pushed the change instead of polling for it. | What are webhooks? |
| Pagination | 100 per page, cursor-based, applied whether you ask or not. | Pagination |
| Errors and rate limits | What each status code means, and when retrying is pointless. | FAQs |
Where to go next
- Environments: production and demo — choose where to build, and request a demo company.
- Authentication methods — pick API Key or OAuth 2.0.
- First steps — create credentials and generate your first token, end to end.
- What are webhooks? — subscribe to changes rather than polling for them.
- Integrations Framework — patterns for building something production-ready.
Building with an AI assistant
Two things make these docs machine-readable, and both produce noticeably better results than pointing a model at the rendered pages:
- Append
.mdto any documentation URL for its Markdown source — for example.../docs/pagination.md. - Fetch
llms.txtfor a complete index of every guide and endpoint, in Markdown and OpenAPI.
The OpenAPI specification itself is at https://api.factorialhr.com/oas/, and accepts a ?version= parameter.
Need a hand?
If something is unclear or does not behave as documented, tell us — it usually means the documentation needs fixing.
Updated 2 days ago