> ## 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.

# Factorial

> Connect Factorial HR to Serval with a company API key to give workflows secure, on-demand access to employees, time off, recruiting, payroll, and the rest of the Factorial API.

## 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

| Capability                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Factorial API request action | Gives 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 checks     | Three built-in checks verify the API key works and can read your Employees and Teams data.                                                                                                                                                                                                                                                                                                                                                                         |
| API context for Serval AI    | The 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](https://apidoc.factorialhr.com/reference/getting-started) 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](https://help.factorialhr.com/en_US/how-to-create-api-keys).

<Steps>
  <Step title="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.
  </Step>

  <Step title="Open Settings > Advanced configuration > API Keys">
    If you don't see this area, ask a Factorial administrator to grant you the right access.
  </Step>

  <Step title="Click Create API Key and name it">
    Use a descriptive name such as "Serval Integration" so it is easy to identify later.
  </Step>

  <Step title="Click Create and copy the key immediately">
    Factorial shows the key only once. If you lose it, revoke it and issue a new one.
  </Step>
</Steps>

<Warning>
  Copy the key as soon as it is created - Factorial will not show it again.
</Warning>

<Note>
  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.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the Factorial integration in Serval">
    Find Factorial in the integrations list (it carries a Beta badge) and start a new connection.
  </Step>

  <Step title="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."
  </Step>

  <Step title="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.
  </Step>

  <Step title="Submit the form">
    Serval stores the key encrypted and normalizes the API URL to a bare host.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## Verifying the connection

The integration ships with three health checks you can run from the connection page:

| Health check              | What it does                                                                                                       | On success                                                         | On failure                                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Test Factorial Connection | Verifies 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 Employees  | Lists 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 Teams      | Lists 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."         |

<Tip>
  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.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The key must come from a company admin">
    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.
  </Accordion>

  <Accordion title="Production keys do not work against demo tenants (and vice versa)">
    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.
  </Accordion>

  <Accordion title="The API URL field accepts almost anything you paste">
    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.
  </Accordion>

  <Accordion title="Pinned to Factorial API version 2026-04-01">
    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.
  </Accordion>

  <Accordion title="Editing the connection keeps existing values on blank">
    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.
  </Accordion>

  <Accordion title="The integration is in Beta">
    Factorial shows a Beta badge in the Serval app. Functionality is fully usable, but surfaces may evolve.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Factorial integration.