> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TalentHR plugin

> HR management with TalentHR - hire, update, terminate and rehire employees, read the directory, book and approve time off, and manage the divisions, departments, locations and job titles those records reference.

Use **TalentHR** through Corsair: one client, typed API calls.

Create a key in TalentHR under Domain settings, API. The request authenticates with HTTP Basic, where the key is the username and the password is ignored; this plugin builds that header for you. The key is scoped to one TalentHR domain, so a key from another domain reads as a missing tenant.

Things to know before you call:

* **A wrong key looks like a missing tenant.** TalentHR answers a refused key with 401 and the body `{"success": false, "error": {"hr_code_key": "not_found_tenancy"}}`. HTTP failures arrive as core's `ApiError`: check `error.status === 401` first, then `error.body.error.hr_code_key` (`not_found_tenancy` when the body names the tenant). A working key on the wrong domain produces the same body.
* **Every answer is an envelope.** Successful calls are `{ success: true, data }` and the plugin returns `data` alone. The deletes answer `{ success: true }` with no `data`, so their result is that object.
* **Updates are not partial.** `employees.update` requires `first_name`, `last_name` and `email` on every call, because TalentHR treats the body as the full contact record rather than a patch. Read the employee first and send those three back with the fields you are changing.
* **Hiring sends email.** `employees.hire` emails the new employee unless you pass `prevent_email: true`.
* **Terminating, rehiring and answering time off also send email.** `employees.terminate` notifies the people given offboarding tasks, `employees.rehire` sends a rehire email unless `prevent_email: true`, and `timeOff.reply` emails the employee the outcome. All of these are `destructive`.
* **Booking time off emails a manager.** `timeOff.create` with `preapproved: false` or without `preapproved` sends the employee's manager an approval email. Passing `preapproved: true` approves it directly when the caller's role allows.
* **Time off amounts are not always strings.** Lists and budgets send amounts as strings with three decimals, such as `"10.000"`, but a `timeOff.create` answer sends `budget` as a number and `working_hours` as `"8.00"`. Treat each amount as a number, a string or null, and convert it before doing arithmetic.
* **Paging is offset based.** `employees.directory` takes `limit` (default 10, maximum 100) and `offset`, and answers `{ total, rows }` where `total` counts every match, not the page.
* **Deletes can be refused.** A division, department or job title that an active job position uses cannot be deleted, and a delete clears that record from benefits, reviews and tasks that referenced it.
* **Rate limit.** TalentHR allows 2000 requests per minute per key and sends no `Retry-After` header. The plugin retries a 429 three times with exponential backoff.

**What you get:**

* 25 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/talenthr better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/talenthr better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/talenthr better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/talenthr better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { talenthr } from '@corsair-dev/talenthr';

export const corsair = createCorsair({
	plugins: [
		talenthr(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the TalentHR API key before the first call: `pnpm corsair setup --plugin=talenthr --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> talenthr()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'talenthr',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List the first page of the directory**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.talenthr.api.employees.directory({ limit: 25 });
```

**Book a day of sick leave**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.talenthr.api.timeOff.create({
	employeeId: 15,
	start_date: '2026-12-01',
	end_date: '2026-12-01',
	timeoff_type_id: 1,
});
```

See the full list on the [API](https://docs.corsair.dev/plugins/talenthr/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/talenthr/api.md)
>
> Every `talenthr.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.