---
updatedAt: 2026-09-11T15:06:12.000Z
agentTools:
  projectIndex: https://apidoc.factorialhr.com/llms.txt
---

# 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](https://apidoc.factorialhr.com/reference/).

## Pick your path

How you authenticate depends on who the integration is for. Decide this first — it shapes your whole setup.

<Callout icon="📘" theme="info">
  ### Building for your own company

  An 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](https://apidoc.factorialhr.com/docs/authentication), then the [API Keys Setup Guide](https://apidoc.factorialhr.com/docs/api-keys).
</Callout>

<Callout icon="📘" theme="info">
  ### Building for other companies

  A 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](https://apidoc.factorialhr.com/docs/oauth2-partner-guide), then [OAuth Scopes](https://apidoc.factorialhr.com/docs/oauth-scopes).
</Callout>

## 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](https://apidoc.factorialhr.com/docs/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](https://apidoc.factorialhr.com/docs/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
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
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`.

<Callout icon="🚧" theme="warn">
  ### Two things that catch people out

  The header is `Authorization`, not `Authentication`. And a `200` with an empty body usually means the credential belongs to the other environment.
</Callout>

## Core concepts

| Concept                | Why it matters on day one                                                 | Guide                                                                   |
| ---------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Environments           | Credentials are not shared between production and demo.                   | [Environments](https://apidoc.factorialhr.com/docs/production-and-demo) |
| Versioning             | Versions are supported for one year; an expired one does not fail loudly. | [API versioning](https://apidoc.factorialhr.com/docs/api-versioning)    |
| Authentication         | An API Key grants everything; OAuth lets you scope access.                | [Authentication](https://apidoc.factorialhr.com/docs/authentication)    |
| Webhooks               | Get pushed the change instead of polling for it.                          | [What are webhooks?](https://apidoc.factorialhr.com/docs/webhooks-what) |
| Pagination             | 100 per page, cursor-based, applied whether you ask or not.               | [Pagination](https://apidoc.factorialhr.com/docs/pagination)            |
| Errors and rate limits | What each status code means, and when retrying is pointless.              | [FAQs](https://apidoc.factorialhr.com/docs/faqs)                        |

## Where to go next

1. **[Environments: production and demo](https://apidoc.factorialhr.com/docs/production-and-demo)** — choose where to build, and request a demo company.
2. **[Authentication methods](https://apidoc.factorialhr.com/docs/authentication)** — pick API Key or OAuth 2.0.
3. **[First steps](https://apidoc.factorialhr.com/docs/first-steps)** — create credentials and generate your first token, end to end.
4. **[What are webhooks?](https://apidoc.factorialhr.com/docs/webhooks-what)** — subscribe to changes rather than polling for them.
5. **[Integrations Framework](https://apidoc.factorialhr.com/docs/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 `.md` to any documentation URL for its Markdown source — for example `.../docs/pagination.md`.
* Fetch [`llms.txt`](https://apidoc.factorialhr.com/llms.txt) for 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.

> **➡️**[**Partner Developers Tech Support**](https://portal.support.factorialhr.com/servicedesk/customer/portal/347/group/478/create/1119)

> **➡️**[**Clients Customer Support**](https://portal.support.factorialhr.com/servicedesk/customer/portal/5/group/7/create/19)