factorial-api-client 1.0.0

Official Python SDK for the Factorial API

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

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")

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()