Recruitee plugin

• The company id is half the credential. A token belongs to one company, and the id is part of every path. Using a token for another company answers 401, so the plugin stores both and refuses to build a request without the id.
• Tokens cannot be regenerated. Revoking one leaves you creating a new token and updating every integration, so a 401 is terminal; the plugin never retries it. A token also carries its creator’s permissions, including removing that user from the company cutting their tokens off from it.
• Three error shapes exist. The current one is { errors: [{ code, data, message }] }; the older ATS routes answer { error, error_code }; and the host can answer a bare 401 with no body. The plugin reads whichever arrived.
• Candidate search takes one filters_json array. candidates.list calls /search/new/candidates and builds that array from query, offer_id, stage, status, department_id and location_id. The route ignores plain query or offset parameters, and answers { hits, total }.
• Offer filters are arrays. offers.list sends statuses[], department_ids[] and location_ids[]; Recruitee ignores a bare status and returns every offer.
• Creates and updates wrap the record. A candidate or offer goes in under a candidate or offer key, and a candidate’s offer assignments sit beside that key as an offers array rather than inside it.
• Paging is page and limit. Candidates, offers and locations return total and next_page (null on the last page). Departments come back in one answer.
• A new offer is a draft. The create and update routes take no status; publishing is a separate step in Recruitee. A job needs description, requirements and at least one of location_ids.
• Drafts take no candidates. candidates.create with the offer_id of a draft offer creates the candidate but places them nowhere, and Recruitee returns no error. Publish the offer first, or assign the candidate later.
• A candidate delete is restorable for 7 days. Recruitee sets deleted_at a week ahead and keeps the candidate in its deleted list until then.
• Stages live on placements. candidates.update edits the profile; moving a candidate to another stage or disqualifying them happens on their placement for an offer, which this plugin does not cover yet.
• Rate limit. 1000 requests per minute per token. Recruitee documents no Retry-After, so a 429 is retried three times with backoff.

• 11 typed API operations

​

Setup

npm install corsair @corsair-dev/recruitee better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/recruitee better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/recruitee better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/recruitee better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { recruitee } from '@corsair-dev/recruitee';

export const corsair = createCorsair({
	plugins: [
		recruitee(),
	],
	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!,
	},
});

recruitee()

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

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.recruitee.api.candidates.list({ offer_id: 42, limit: 25 });

const tenant = corsair.withTenant('acme');
await tenant.recruitee.api.candidates.create({
	name: 'John Smith',
	emails: ['john@example.com'],
	offer_id: 42,
});

​

What’s next