Skip to main content

​
About Factorial

Factorial is an HRIS for small and mid-sized companies that covers the employee lifecycle: onboarding, time off, attendance, payroll, recruiting (ATS), documents, and reporting. Serval connects to Factorial using a company-scoped API key stored encrypted by Serval, and your workflows get typed, proxied access to the full Factorial REST API (version 2026-04-01). Workflow code never sees the raw key - Serval injects it on every request. This integration is currently in Beta and shows a Beta badge in the Serval app. Authentication: API key, sent by Serval as the x-api-key header on every request to Factorial. Data sync: On-demand only. There is no background sync, entity ingestion, or pre-installed workflows - workflows call Factorial at the moment they need data.

​
What the Factorial integration enables

CapabilityDescription
Factorial API request actionGives workflows typed access to the Factorial REST API (version 2026-04-01) - 382 endpoints across 37 areas, including employees, teams, time off, attendance, recruiting (candidates, applications, job postings), contracts, payroll, documents, custom fields and custom resources, expenses, finance, holidays, IT management, locations, performance, project management, shifts, tasks, time planning, trainings, work schedules, and webhook subscriptions.
Connection health checksThree built-in checks verify the API key works and can read your Employees and Teams data.
API context for Serval AIThe full Factorial API surface is indexed as “Factorial v2026-04-01 API”, so AI-assisted workflow authoring can discover and call Factorial endpoints for you.
Anything defined in the Factorial API can be accessed through Serval.

​
Get your credentials

Serval needs a Factorial API key created by a company admin. Keys are scoped to your whole company (not to an individual user) and carry admin-level access, so treat the key like a service-account credential. Factorial’s official guide is here: How to create API keys in Factorial.
1

Log in to Factorial as a company admin

The key inherits admin-level, company-wide access, so it must be created from an admin account.
2

Open Settings > Advanced configuration > API Keys

If you don’t see this area, ask a Factorial administrator to grant you the right access.
3

Click Create API Key and name it

Use a descriptive name such as “Serval Integration” so it is easy to identify later.
4

Click Create and copy the key immediately

Factorial shows the key only once. If you lose it, revoke it and issue a new one.
Copy the key as soon as it is created - Factorial will not show it again.
Connecting a Factorial demo or non-default region tenant? Note its API host (for example, api.eu2.demo.factorial.dev) - you will enter it in the optional API URL field in Serval. Production tenants can skip this entirely.

​
Connect in Serval

1

Open the Factorial integration in Serval

Find Factorial in the integrations list (it carries a Beta badge) and start a new connection.
2

Enter your API Key (required)

Paste the key you copied from Factorial. The field’s helper text reads: “Generated in Factorial → Settings → Advanced configuration → API Keys by a company admin. Sent as the x-api-key header.”
3

Leave API URL (optional) blank for production

The placeholder shows api.factorialhr.com, which is used automatically when the field is blank. The helper text explains that production tenants should leave it blank and that it is only needed when connecting a Factorial demo or non-default region tenant (for example, api.eu2.demo.factorial.dev). You can paste a full URL from Factorial’s docs - Serval trims it down to just the host.
4

Submit the form

Serval stores the key encrypted and normalizes the API URL to a bare host.
Editing the connection later is safe: the saved key appears as a locked, masked value - bullets plus its last 4 characters - with a control to replace it (a Replace button on the reconnect form, a pencil icon on the connection settings page). Leave it untouched to keep the existing key; even submitting an empty replacement keeps the existing key. The API URL field comes pre-filled with the saved host, and clearing it keeps that host rather than resetting anything.

​
Verifying the connection

The integration ships with three health checks you can run from the connection page:
Health checkWhat it doesOn successOn failure
Test Factorial ConnectionVerifies Serval can reach Factorial and that the API key is accepted, by reading the key’s own public credentials.”Successfully connected to Factorial and verified the API key.""Unable to connect to Factorial. Please verify your API key is valid and was generated by an admin user.”
List Factorial EmployeesLists active employees and reports the count.”Successfully listed employees from Factorial (count: [number]).""Unable to list employees from Factorial. Please verify the API key has admin access to the Employees resource.”
List Factorial TeamsLists teams and reports the count.”Successfully listed teams from Factorial (count: [number]).""Unable to list teams from Factorial. Please verify the API key has admin access to the Teams resource.”
If “Test Factorial Connection” passes but the Employees or Teams checks fail, your key is valid but lacks admin access to those resources. Re-issue the key from a company admin account in Factorial and update the connection.

​
Gotchas and troubleshooting

Factorial API keys are company-scoped, not user-scoped, and the health checks require admin access to the Employees and Teams resources. If the connection test fails with a message about the key being “valid and generated by an admin user”, have a company admin create the key. Because the key grants company-wide access, treat it like a service-account credential.
Serval only sends your key to official Factorial API hosts - production (api.factorialhr.com) and Factorial demo/dev hosts (for example, api.eu2.demo.factorial.dev). Demo and production are separate environments, so always pair the key with the matching tenant’s host: a production key will not authenticate against a demo API URL. Requests to any other host never receive your key.
Serval reduces whatever you paste to a bare host: it trims whitespace, lowercases, strips any leading http:// or https://, and drops any path (including a full base URL copied from Factorial’s API docs). On a new connection, leaving the field blank - or pasting something that reduces to nothing, like a bare scheme - selects the production host api.factorialhr.com. If a connection points at the wrong tenant, check what host the field resolved to.
The typed action surface and the AI’s knowledge of Factorial endpoints are generated from Factorial’s 2026-04-01 API specification. Endpoints that only exist in other Factorial API versions are not part of the typed surface.
On the edit form, the saved key shows as bullets plus its last 4 characters; submitting without replacing it keeps the existing key, and even an empty replacement keeps the existing key. The API URL field is pre-filled with the saved host, and a cleared or whitespace-only API URL keeps that host rather than resetting to the production default - so to move a connection from a demo host back to production, type api.factorialhr.com explicitly. Nothing is silently cleared - only values you actually replace are changed.
Factorial shows a Beta badge in the Serval app. Functionality is fully usable, but surfaces may evolve.
Need help? Contact support@serval.com for assistance with your Factorial integration.