Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.serval.com/llms.txt

Use this file to discover all available pages before exploring further.

​
About Factorial

Factorial is a modern HRIS used by small and mid-sized companies to manage the full employee lifecycle: onboarding, time off, payroll, performance, documents, and reporting, from a single platform.

​
What the Factorial integration enables

CapabilityDescription
Workflow AutomationBuild Serval workflows on top of any resource exposed by Factorial’s REST API
All resources documented in the Factorial API Reference are reachable from Serval workflows once the integration is connected.

​
Factorial configuration (in Factorial)

​
Prerequisites

  • Admin access to your Factorial company
  • Ability to view Settings in the Factorial UI

​
Understanding Factorial API authentication

Factorial exposes its public API via API keys scoped to a company (not an individual user). API keys grant full admin access on behalf of the company, so treat them with the same care as a service account credential.
Factorial issues API keys as long opaque tokens. They are passed on every request via the x-api-key header. Serval handles header injection automatically.

​
Step 1: Generate an API key

1

Open API Keys settings

  1. Log in to Factorial as a company admin
  2. Navigate to Settings → Advanced configuration → API Keys
  3. Click Create API Key
If you don’t see this option, ask your Factorial administrator to enable the API or grant you the right role. Full instructions are in Factorial’s help center article.
2

Name and copy the key

  1. Give the key a descriptive name (e.g. “Serval Integration”)
  2. Click Create and copy the generated key immediately
Factorial only shows the API key once at creation. Store it somewhere secure. If you lose it you’ll need to revoke and re-issue.

​
Serval configuration

1

Open the Factorial integration in Serval

  1. In Serval, go to Applications → Available → Factorial
  2. Click Connect
2

Enter your credentials

FieldDescriptionExample
API KeyThe API key generated in Factorial••••••••••••••••••••
API URL (optional)Custom Factorial host. Leave blank for production.api.eu2.demo.factorial.dev
Almost all customers leave API URL blank. Serval defaults to api.factorialhr.com. Only fill it in if you’re connecting a Factorial demo tenant or a non-default region.
3

Submit and verify

  1. Click Submit
  2. Serval will run a connection healthcheck against Factorial’s API
  3. Once verified, you can use Factorial in your workflows

​
How authentication works

Factorial uses a static API key sent on every request. When Serval calls Factorial on your behalf, it:
  1. Looks up the encrypted API key tied to your integration install
  2. Injects the header x-api-key: <your-api-key> on the proxied request
  3. Forwards to the API URL on file (production by default)
Workflow code never sees the raw API key.

​
Using Factorial in workflows

Once connected, you can use Factorial in your Serval workflows to automate HR processes:
  • Employee management: List, search, create, and update employees
  • Teams & locations: Read company structure and team membership
  • Time off: Manage leave types, balances, and requests
  • Documents: Upload and manage employee documents
  • Reporting: Pull HR data into downstream systems
The Factorial integration covers every endpoint in the Factorial API Reference. Browse the reference to discover all available capabilities.

​
Troubleshooting

If the connection healthcheck fails with 401:
  • Verify the API key was copied without leading/trailing whitespace
  • Confirm the key hasn’t been revoked in Factorial → Settings → Advanced configuration → API Keys
  • If you’re connecting a Factorial demo or regional tenant, double-check the API URL field matches the host shown in Factorial’s API docs Server selector
404s usually mean the endpoint path doesn’t exist on your tenant’s Factorial API version. Confirm the resource path against the API reference. Factorial maintains multiple API versions and not every resource exists in every version.
Factorial API keys are scoped to a single cell. A key issued in production will not authenticate against api.eu2.demo.factorial.dev and vice versa. Generate a key from the same tenant whose API URL you’re targeting.

​
Additional Resources

Factorial API Reference

Complete API reference for Factorial

How to create API keys in Factorial

Step-by-step guide for issuing API keys
Need help? Contact support@serval.com for assistance with your Factorial integration.