---
updatedAt: 2026-07-09T09:58:04.000Z
agentTools:
  projectIndex: https://apidoc.factorialhr.com/llms.txt
---

# SDKs

Official TypeScript and Python client libraries for the Factorial API. Auto-generated from the same OpenAPI spec as this reference, so always in sync. Skip hand-rolled HTTP: get typed methods, auth, pagination, and webhooks out of the box.

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.

| Language   | Package                                                                                                                 | Registry |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- | -------- |
| TypeScript | <Anchor target="_blank" href="https://www.npmjs.com/package/@factorialco/api-client">`@factorialco/api-client`</Anchor> | npm      |
| Python     | <Anchor target="_blank" href="https://pypi.org/project/factorial-api-client/">`factorial-api-client`</Anchor>           | PyPI     |

Source and full documentation: <Anchor target="_blank" href="https://github.com/factorialco/factorial-api-sdks">github.com/factorialco/factorial-api-sdks</Anchor>

## Overview

Install and make your first call in under a minute.

**TypeScript**

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

```ts
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**

```bash
pip install factorial-api-client
```

```python
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:

| SDK major | 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 [API versioning](https://apidoc.factorialhr.com/docs/api-versioning).

## Authentication

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

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

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

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

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

See [Pagination](https://apidoc.factorialhr.com/docs/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.

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

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

```python
# 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](https://apidoc.factorialhr.com/docs/what-are-webhooks) section for subscriptions, policies, and delivery details.

***

Building integrations with an AI coding agent? See [AI Agents](https://apidoc.factorialhr.com/docs/ai-agents) for the installable SDK skill. Full method-level docs, error handling, and examples live in the <Anchor target="_blank" href="https://github.com/factorialco/factorial-api-sdks">GitHub README</Anchor>.