Skip to main content
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

2

Add the plugin

corsair.ts
With multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.
3

Choose authentication

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.

Example API calls

List the first page of the directory
Book a day of sick leave
See the full list on the API page.

What’s next

API reference

Every talenthr.api.* operation with input and output types.

Connect / OAuth

createLink, Hub delivery, and tenant connect flows.

Use with agents

Expose this plugin’s operations as MCP tools.