Factorial API SDKs

Official auto-generated SDKs for the Factorial API, available for TypeScript and Python.

Both SDKs are generated from the OpenAPI spec and wrapped with a generated FactorialClient providing clean domain-namespaced access and cursor pagination helpers.

SDKs

TypeScript · @factorialco/api-client

npm install @factorialco/api-client

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

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

const page = await client.employees.employees.list();
for await (const emp of client.employees.employees.paginate({ maxItems: 50 })) {
  console.log(emp.full_name);
}

→ Full docs

---

Python · factorial-api-client

pip install factorial-api-client

from factorial_api_client import FactorialClient

client = FactorialClient(api_key="YOUR_KEY")

result = client.employees.employee.list()
for emp in client.employees.employee.paginate(max_items=50):
    print(emp.full_name)

→ Full docs

---

Versioning

Both SDKs use 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). To release a new SDK version:

1. Run the release script in the relevant SDK directory.
2. Enter the API version date (yyyy-mm-dd) when prompted.
3. The script fetches the spec from https://api.factorialhr.com/oas/?version=<date>, regenerates all generated code, and bumps the semver (--bump major|minor|patch, default patch).
4. After building, it asks whether to publish — answer y to push to npm/PyPI or n to skip.

See the per-SDK READMEs for full instructions: TypeScript · Python

Development

TypeScript

Generate SDK from latest spec

cd typescript
npm run generate

Fetches the OpenAPI spec from https://api.factorialhr.com/oas/?version=<date> and regenerates all src/generated/*.gen.ts files. Override the URL with:

OPENAPI_SPEC_URL=./local-spec.json npm run generate

Test against the live API

FACTORIAL_API_KEY=your_key npm run test:api
# or with OAuth token:
FACTORIAL_OAUTH_TOKEN=your_token npm run test:api

Release a new version

npm run release                    # patch bump (default)
npm run release -- --bump minor    # minor bump
npm run release -- --bump major    # major bump
npm run release:dry-run            # preview only — no writes, no publish

The release script:

1. Prompts for the API version date (yyyy-mm-dd).
2. Fetches the spec from https://api.factorialhr.com/oas/?version=<date>.
3. Regenerates src/generated/ (stage 1) and src/sdk.ts (stage 2).
4. Bumps the SDK semver (--bump major|minor|patch, default patch).
5. Builds the package, then asks whether to publish to npm.

---

Authentication

Both SDKs support:

• API key — via apiKey: / api_key= (sent as x-api-key header)
• OAuth2 bearer token — via token: / token= (sent as Authorization: Bearer)