SDKs

Factorial ships official client libraries so you don't have to hand-roll HTTP calls, auth headers, or pagination loops. Both SDKs are auto-generated from the same OpenAPI spec that powers this reference, so they stay in sync with the API.

Source and full documentation: github.com/factorialco/factorial-api-sdks

Overview

Install and make your first call in under a minute.

TypeScript

npm install @factorialco/api-client@2026-07-01

import { FactorialClient } from "@factorialco/api-client";

const client = new FactorialClient({ apiKey: process.env.FACTORIAL_API_KEY });

const { data: { data, meta } = {} } = await client.employees.employees.list();
console.log(`${meta.total} employees total`);

Python

pip install factorial-api-client

from factorial_api_client import FactorialClient

client = FactorialClient(api_key="YOUR_KEY")

result = client.employees.employee.list()
print(len(result.data), "employees on this page")

Resources are grouped by domain, mirroring the API hierarchy: client.employees.employees, client.ats.applications, client.timeoff.leaves, and so on. Each resource exposes the standard list / get / create / update / delete methods plus any custom actions.

Versioning

SDKs use standard semver, independent of the dated API version. The major version tracks the Factorial API version:

Factorial releases new API versions quarterly (Jan/Apr/Jul/Oct). See API versioning.

Authentication

Both SDKs accept an API key (sent as x-api-key) or an OAuth2 bearer token (sent as Authorization: Bearer).

// TypeScript
new FactorialClient({ apiKey: process.env.FACTORIAL_API_KEY }); // API key
new FactorialClient({ token: getAccessToken() });               // OAuth2 bearer

# Python
FactorialClient(api_key="YOUR_KEY")        # API key
FactorialClient(token="YOUR_BEARER_TOKEN") # OAuth2 bearer

When you omit credentials, the client falls back to the FACTORIAL_API_KEY, FACTORIAL_TOKEN, and FACTORIAL_BASE_URL environment variables.

The Factorial API key is JWT-formatted but must be sent as x-api-key, not as a bearer token. The SDK handles this for you.

See Authentication methods for the full auth guide.

Pagination

The API uses cursor-based pagination. Every list endpoint returns a data array plus a meta object with has_next_page, end_cursor, and total. The SDKs give you three ways to consume it:

• list() — a single page (up to 100 items).
• paginate() — an iterator that streams across pages automatically (Python also has paginate_async()).
• all() — collects every page into one array/list (supports a safety cap).

// TypeScript — stream every employee across all pages
for await (const employee of client.employees.employees.paginate()) {
  console.log(employee.full_name);
}

# Python — stop after 100 items
for emp in client.employees.employee.paginate(max_items=100):
    print(emp.full_name)

See Pagination for the underlying mechanics.

Webhooks

Each SDK includes a typed webhook catalog generated from the spec's webhooks object, re-exported from the package root. You get per-event payload types, a WebhookSubscriptionType union, a subscription_type → payload-type map, and a runtime WEBHOOK_CATALOG. Subscriptions are managed through the same client.

// TypeScript
import type { AtsApplicationCreateWebhook } from "@factorialco/api-client";

function onApplicationCreated(payload: AtsApplicationCreateWebhook) {
  console.log(payload.id);
}

# Python
from factorial_api_client import AtsApplicationCreateWebhook

def on_application_created(payload: AtsApplicationCreateWebhook) -> None:
    print(payload.id)

Factorial delivers the resource object at the top level of the POST body (no { type, data } envelope). The challenge secret you set on subscription is echoed back in the x-factorial-wh-challenge header so you can verify each delivery.

See the Webhooks section for subscriptions, policies, and delivery details.

Building integrations with an AI coding agent? See AI Agents for the installable SDK skill. Full method-level docs, error handling, and examples live in the GitHub README.