# Factorial (slim)

> Factorial is an HR platform from Barcelona for employee records, time off, attendance, payroll data, recruiting and expenses. Agents reach it through a versioned REST API with API keys or OAuth 2.0, webhooks and a hosted MCP server.

- Full: https://www.anchorterminal.com/tools/factorial.md (~8,350 tokens) · this version ~2,280 tokens · JSON https://www.anchorterminal.com/tools/factorial.json · canonical https://www.anchorterminal.com/tools/factorial
- Index: https://www.anchorterminal.com/llms.txt · API: https://www.anchorterminal.com/api/v1/index.json · Updated: 2026-10-08

**B · 66.3/100 · rank #239 of 722 · #2 in HR & employee operations · not agent-ready · confidence medium**


Assessment: A public OpenAPI 3.1 definition covers 615 operations, including leave approval and employee termination, and OAuth apps can be limited to 33 scopes. API keys always grant every scope and never expire. No idempotency keys exist, and a request to an expired API version is answered in an older schema with no error.

## Facts

- Kind: HTTP API · vendor: Everyday Software, S.L. · category: HR & employee operations · legal entity: Everyday Software, S.L. · provenance 82/100
- Endpoint: `https://api.factorialhr.com` (HTTP)
- Auth: OAuth or key · pricing: Paid · x402: no · licence: Proprietary service under Factorial's terms and conditions. The TypeScript and Python SDKs are MIT
- Probe metrics: not measured yet (probes haven't run)
- Surface graded: The public REST API at `https://api.factorialhr.com/api/2026-10-01/resources/...`. The hosted MCP server is described but its tool definitions sit behind an OAuth login and were not read
- API coverage: 615 operations in 38 groups. The largest are performance (56), project management (52), ATS (45), time off (43), finance (42), contracts (41), attendance (34) and trainings (34). Employees has 8, including create with contract, invite, terminate and unterminate
- Credentials: API key in `x-api-key`, company-wide, all scopes, no expiry, revocable in settings. OAuth 2.0 authorisation code (PKCE for public clients) through Factorial ID at `id.factorialhr.com`, with company tokens and user tokens that last 1 hour and renew by refresh token
- Scopes: 33 OAuth scopes in the definition, with `read` and `write` plus areas such as `employees`, `time_off`, `time_tracking`, `documents`, `payroll`, `recruitment` and `tasks`. A user token is further limited by the employee's permission group, and fields outside it come back as null
- MCP server: `https://mcp.factorialhr.com`, Streamable HTTP, OAuth 2.0 with dynamic client registration. Its metadata lists 10 scopes (`one:read`, `one:write`, `employees`, `tasks`, `time_off`, `time_tracking` and four more). Factorial One requests consume plan credits, direct tools currently do not
- Rate limits: 200 `POST` requests a minute per the FAQ. No limit for other methods and no `Retry-After` header found in the reviewed documentation. Suggested backoff is 2, 4, 8 then 16 seconds
- Errors: 400, 401, 403, 404, 422, 429 and 5xx explained in the FAQ. Some 422 responses carry a machine-readable `code`, and messages may be in Spanish, French or German. The OpenAPI definition documents only 200 and 201 responses. An unauthenticated call returned 401 with `{"errors":null}`
- Pagination: Cursor-based on every list endpoint, 100 records by default and at most, with `after_id` and `before_id` and a `meta` block holding `has_next_page`, `end_cursor` and `total`
- Webhooks: 137 event types, managed through `/api_public/webhook_subscriptions`. The payload is the resource itself with no envelope or delivery ID. A `challenge` secret is echoed in `x-factorial-wh-challenge`. Up to 20 attempts over 48 hours, then the subscription is disabled
- Time off: Create, update and delete leaves, approve, approve all and reject, plus leave types, allowances, policies and blocked periods
- Versioning: Dated versions in the path (2026-10-01 current, released 5 October 2026, with 2027-01-01 as release candidate). One version a quarter, each supported for one year. Webhook subscriptions carry their own `api_version`
- SDKs: `@factorialco/api-client` 3.0.0 on npm and `factorial-api-client` 3.0.0 on PyPI (both 5 October 2026, MIT, Python 3.11 or later), a Ruby SDK in the same repository, and a `factorial-api-sdks` skill installed with `npx skills add`. The SDK major version tracks the API version
- Sandbox: A demo environment at `api.eu2.demo.factorial.dev` with separate credentials, requested through an account manager or account executive. Its data can be deleted at any time
- SLA: 99.9 per cent monthly uptime, with a service credit of 5 per cent of the period's charges when missed, per the trust centre. Support target of 90 per cent of tickets answered within 4 hours
- Certifications: SOC 2 Type 2, SOC 3, ISO/IEC 27001:2022 and ENS RD311/2022 High per trust.factorial.co. The trust centre names a HackerOne bug bounty and annual third-party penetration tests
- Status: status.factorialhr.com on Statuspage, 14 components including API & backend and Authentication system. The newest incident in the feed is dated 1 June 2026
- Data location: Customer data stored in the EU on AWS (Frankfurt) and Azure (Frankfurt and Sweden). AI functions use Azure OpenAI, Gemini and Cloudflare AI under contracts that bar training on customer data, per the trust centre
- Prices: Starting price $8 per seat per month

- Scores: Reliability 88, Performance pending, Schema & documentation 77, Agent ergonomics 58, Security & auth 65, Payments & pricing 10, Task success pending, Maintenance & community 84, Transparency & trust 78 · total over the 7 assessed categories
- Why: Reliability, Graded on the public REST API with the hosted lines. · Schema & documentation, A public OpenAPI 3.1.0 definition at `https://api.factorialhr.com/oas/` covers 615 operations and 137 webhook events (25). · Agent ergonomics, List responses are capped at 100 records and can be narrowed by ID and date filters. · Security & auth, OAuth 2.0 with 33 scopes, PKCE for public clients, 1-hour tokens, refresh and a revoke endpoint, and user tokens bound to a permission group… · Payments & pricing, No x402, MPP or L402 (0). · Maintenance & community, API version 2026-10-01 was released on 5 October 2026, with SDK 3.0.0 the same day (30). · Transparency & trust, Closed service with public terms amended 12 December 2025, and MIT SDKs.
- Sources: 29, open questions: 9, both in the full twin
- Capabilities: hr.employees, hr.time-off, hr.org, hr.documents, recruiting.applications, recruiting.jobs, recruiting.candidates, spend.expenses, tasks.create
- JSON: https://www.anchorterminal.com/api/v1/tools/factorial.json
- Verify (for the vendor): the badge `https://www.anchorterminal.com/badges/factorial.svg` or a link to https://www.anchorterminal.com/tools/factorial from a page on factorialhr.com or factorial.com or one of their subdomains, or the README of github.com/factorialco/factorial-api-sdks, then `POST https://www.anchorterminal.com/api/v1/verify` `{"slug", "url"}` or `verify_listing` at /mcp; re-checked weekly, no effect on the grade. Snippets in the full twin.

## Before you call it

1. Send an API key in `x-api-key` and an OAuth token in `Authorization: Bearer`. The key is JWT-formatted but is rejected as a bearer token
2. Pin the version in the path, such as `/api/2026-10-01/resources/...`, and migrate within a year. Expired versions answer in an older schema without an error
3. Treat a 200 with an empty body as a credential from the other environment. Production is `api.factorialhr.com` and demo is `api.eu2.demo.factorial.dev`
4. Page with `limit=100` and pass `meta.end_cursor` as `after_id`. A larger limit is capped at 100
5. Check whether a record exists before retrying a create. Retry only 429 and 5xx with backoff, and branch on `code` for 422 because messages are localised

## Connect

```bash
npm install @factorialco/api-client
```

```bash
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>'
```
Full config and headless snippets are in the full page. Through letme (picks today, calling later): https://letme.dev/factorial

## Similar tools

| Tool | Grade | Score | Shared capabilities | Slim |
| --- | --- | --- | --- | --- |
| BambooHR | C | 61.7 | hr.employees, hr.time-off, hr.org, hr.documents, recruiting.applications, recruiting.jobs | https://www.anchorterminal.com/tools/bamboohr.min.md |
| Workable | C | 61.7 | recruiting.candidates, recruiting.jobs, recruiting.applications, hr.employees, hr.time-off, hr.org | https://www.anchorterminal.com/tools/workable.min.md |
| Rippling | C | 60.8 | hr.employees, hr.time-off, hr.org, hr.documents, recruiting.candidates | https://www.anchorterminal.com/tools/rippling.min.md |
| Deel | B | 69.1 | hr.employees, hr.time-off, hr.org, hr.documents | https://www.anchorterminal.com/tools/deel.min.md |
| HiBob | C | 57 | hr.employees, hr.time-off, hr.org, hr.documents | https://www.anchorterminal.com/tools/hibob.min.md |


## Panel reviews (0, desk reviews from public material, no calls made)