This release is a pre-release and may not be stable for production use.
factorial-api-client (Python)
Official Python SDK for the Factorial API.
Versioning
The SDK uses standard semver (MAJOR.MINOR.PATCH), independent of the Factorial API version date.
| SDK version | Factorial API version |
|---|---|
1.x.y |
2026-04-01 |
2.x.y |
2026-07-01 |
Factorial releases new API versions quarterly (Jan/Apr/Jul/Oct).
See the Factorial API versioning docs for details.
Installation
pip install factorial-api-client
Quick start
from factorial_api_client import FactorialClient
client = FactorialClient(api_key="YOUR_KEY")
# First page only
result = client.employees.employee.list()
employees = result.data
# Cursor-paginated iterator (sync)
for emp in client.employees.employee.paginate(max_items=100):
print(emp.full_name)
# Collect all pages into a list
all_employees = client.employees.employee.all()
# Async iterator
import asyncio
async def main():
async for emp in await client.employees.employee.paginate_async(max_items=100):
print(emp.full_name)
asyncio.run(main())
Authentication
Pass your API key via api_key= or an OAuth2 bearer token via token=:
# API key (sent as x-api-key header)
client = FactorialClient(api_key="YOUR_KEY")
# OAuth2 bearer token
client = FactorialClient(token="YOUR_BEARER_TOKEN")
Environment variables
When an argument is omitted, the client falls back to environment variables. Explicit arguments always take precedence.
| Variable | Maps to | Sent as |
|---|---|---|
FACTORIAL_API_KEY |
api_key |
x-api-key header |
FACTORIAL_TOKEN |
token |
Authorization: Bearer |
FACTORIAL_BASE_URL |
base_url |
— (defaults to https://api.factorialhr.com) |
# No arguments needed — reads FACTORIAL_API_KEY / FACTORIAL_TOKEN / FACTORIAL_BASE_URL
client = FactorialClient()
Error handling
The client fails loudly on non-2xx responses (bad/expired token, wrong base
URL, 4xx/5xx) instead of silently returning None. These raise
UnexpectedStatus:
from factorial_api_client.generated.errors import UnexpectedStatus
try:
employees = client.employees.employee.list()
except UnexpectedStatus as e:
print(e.status_code) # e.g. 401
print(e.content) # raw response body (bytes)
Domain namespaces
The client is organised as client.{domain}.{resource}.{method}().
| Domain | Example |
|---|---|
employees |
client.employees.employee.list() |
ats |
client.ats.application.list() |
attendance |
client.attendance.shift.list() |
timeoff |
client.timeoff.leave.list() |
contracts |
client.contracts.contract_version.list() |
payroll |
client.payroll.supplement.list() |
documents |
client.documents.document.list() |
performance |
client.performance.review_process.list() |
| ... | 36 domains total |
Available methods per resource: list, get, create, update, delete,
paginate, paginate_async, all, plus any custom action endpoints.
Pagination
All list endpoints support cursor-based pagination via paginate() / paginate_async() / all():
# Stop after 50 items
for emp in client.employees.employee.paginate(max_items=50):
...
# Collect everything (use carefully on large datasets)
all_leaves = client.timeoff.leave.all()
Webhooks
Manage subscriptions through the client, and type your handler payloads with the generated webhook catalog (re-exported from the package root).
from factorial_api_client import (
FactorialClient,
AtsApplicationCreateWebhook,
WEBHOOK_CATALOG,
WEBHOOK_PAYLOAD_TYPES,
)
client = FactorialClient(api_key="YOUR_KEY")
# Subscribe to an event. The `challenge` is a secret you choose; Factorial echoes
# it back in the `x-factorial-wh-challenge` header on every delivery so you can
# verify the request really came from Factorial.
client.api_public.webhook_subscription.create(body={
"subscription_type": "ats/application/create",
"target_url": "https://example.com/webhooks/factorial",
"company_id": 55,
"challenge": "a-random-secret-you-generate",
})
# Type a handler directly
def on_application_created(payload: AtsApplicationCreateWebhook) -> None:
print(payload.id)
# Look up the payload model class for a subscription_type at runtime
model_cls = WEBHOOK_PAYLOAD_TYPES["ats/application/create"]
print(len(WEBHOOK_CATALOG), "webhook events available")
Factorial delivers the resource object at the top level of the POST body (no
{type, data} envelope). A full event→payload reference and an SDK usage guide
for coding agents are available as a skill:
npx skills add https://github.com/factorialco/factorial-api-sdks --skill factorial-api-sdks
1 maintainer
Metadata
1 maintainer
Release files for factorial-api-client 3.0.0b2026100107
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| factorial_api_client-3.0.0b2026100107.tar.gz | 478.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| factorial_api_client-3.0.0b2026100107-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.3 MB
Release files / factorial_api_client-3.0.0b2026100107.tar.gz
| Download URL | factorial_api_client-3.0.0b2026100107.tar.gz |
|---|---|
| Size | 478.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ef564b952b0442c8ff4a9705d0f74944cc588e34ee768d18a0263dd508496f4a
|
|
BLAKE2b-256 checksum How to use checksums |
8b91c031b1ef889b056775fd82c769a97a3878db97624804a40bde68272c9597
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / factorial_api_client-3.0.0b2026100107-py3-none-any.whl
| Download URL | factorial_api_client-3.0.0b2026100107-py3-none-any.whl |
|---|---|
| Size | 1.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
90e74a5960d66efc68a7e3d1e4bc60466bdfd5f7f57fc75d0bd14166f0c7d67d
|
|
BLAKE2b-256 checksum How to use checksums |
48fc4de7460eb5fafd5ffb1e29566f2b1123952598bc30c82d25737e79b1fad2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
