- 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’sApiError: checkerror.status === 401first, thenerror.body.error.hr_code_key(not_found_tenancywhen 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 returnsdataalone. The deletes answer{ success: true }with nodata, so their result is that object. - Updates are not partial.
employees.updaterequiresfirst_name,last_nameandemailon 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.hireemails the new employee unless you passprevent_email: true. - Terminating, rehiring and answering time off also send email.
employees.terminatenotifies the people given offboarding tasks,employees.rehiresends a rehire email unlessprevent_email: true, andtimeOff.replyemails the employee the outcome. All of these aredestructive. - Booking time off emails a manager.
timeOff.createwithpreapproved: falseor withoutpreapprovedsends the employee’s manager an approval email. Passingpreapproved: trueapproves 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 atimeOff.createanswer sendsbudgetas a number andworking_hoursas"8.00". Treat each amount as a number, a string or null, and convert it before doing arithmetic. - Paging is offset based.
employees.directorytakeslimit(default 10, maximum 100) andoffset, and answers{ total, rows }wheretotalcounts 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-Afterheader. The plugin retries a 429 three times with exponential backoff.
- 25 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the TalentHR API key before the first call: More: API Key
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.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 directoryWhat’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.