Employer self-service

Let approved employers claim companies, manage jobs, and review applicants.

Build an employer portal around board.me.companies. Every method is authenticated and scoped to a company membership; public company data remains under board.companies.

Prerequisites

board.context().features.employers is true.
A server-owned employer session.
A protected account area with cache: 'no-store'.
UI states for approved, pending_work_email, awaiting_admin, and rejected memberships.

Claim a company

1// src/data/employer.ts
2import type { FetchOptions } from '@cavuno/board';
3
4import { board } from '../lib/board';
5
6function session(accessToken: string): FetchOptions {
7  return {
8    cache: 'no-store',
9    headers: { authorization: `Bearer ${accessToken}` },
10  };
11}
12
13export async function claimCompany(
14  accessToken: string,
15  companySlug: string,
16) {
17  return board.me.companies.claim(
18    companySlug,
19    session(accessToken),
20  );
21}
22
23export async function sendWorkEmail(
24  accessToken: string,
25  companySlug: string,
26  workEmail: string,
27) {
28  return board.me.companies.workEmail.verify(
29    companySlug,
30    { workEmail },
31    session(accessToken),
32  );
33}

If the membership is pending_work_email, send the verification link. Consume the emailed token with board.auth.verifyWorkEmail — the link carries only a token, so there is no company slug and no board-user session:

1const membership = await board.auth.verifyWorkEmail({ token });

Do not unlock management screens until the returned membership is approved.

Create and publish a job

1export async function createEmployerJob(
2  accessToken: string,
3  companySlug: string,
4) {
5  const options = session(accessToken);
6  const draft = await board.me.companies.jobs.create(
7    companySlug,
8    {
9      title: 'Staff Engineer',
10      description: 'Build reliable systems for our customers.',
11      applicationUrl: 'https://acme.example/careers/staff-engineer',
12      employmentType: 'full_time',
13      remoteOption: 'remote',
14      remotePermits: [{ type: 'worldwide', value: 'worldwide' }],
15    },
16    options,
17  );
18
19  return board.me.companies.jobs.publish(
20    companySlug,
21    draft.id,
22    options,
23  );
24}

New jobs are held drafts. publish works only while an existing paid window permits it. A held draft that needs billing must use jobs.checkout; branch on checkout, published, pending_approval, or invoice_sent. A free post (or invoice publish-on-issue) returns pending_approval when the board requires free-job approval — show an awaiting-review state. The job’s status becomes pending_approval; like a draft, it is not public, and only the board operator can publish it. Bundle, subscription, and member-credit posts still return published. Never infer publication from a browser redirect.

1export async function checkoutEmployerJob(
2  accessToken: string,
3  companySlug: string,
4  jobId: string,
5  planId: string,
6) {
7  const result = await board.me.companies.jobs.checkout(
8    companySlug,
9    jobId,
10    { billing: { type: 'new', planId } },
11    session(accessToken),
12  );
13
14  switch (result.status) {
15    case 'checkout':
16      return { redirectTo: result.checkoutUrl } as const;
17    case 'published':
18      return { jobSlug: result.jobSlug } as const;
19    case 'pending_approval':
20      return { message: 'Your job is awaiting approval.' } as const;
21    case 'invoice_sent':
22      return { message: 'Your invoice has been sent.' } as const;
23  }
24}

Load the applicant pipeline

1export async function loadPipeline(
2  accessToken: string,
3  companySlug: string,
4  jobId: string,
5) {
6  return board.me.companies.applicants.list(
7    companySlug,
8    { job: jobId },
9    session(accessToken),
10  );
11}
12
13export async function moveApplicant(
14  accessToken: string,
15  companySlug: string,
16  applicationId: string,
17  stageId: string,
18) {
19  const options = session(accessToken);
20  await board.me.companies.applicants.move(
21    companySlug,
22    applicationId,
23    { stageId },
24    options,
25  );
26
27  // Applicant mutations return 204; re-read the pipeline for fresh state.
28}

Use the stage order returned by the pipeline. Do not maintain a second ordering model in local storage.

Source candidates onto a job

A job's sourced shortlist is the talent list (saved search) linked to it; a job has at most one. Shortlist a candidate by saving them to that list with board.me.companies.talentLists.members.add, and take them off with members.remove, which also removes their pipeline row while it is a sourced row still at Shortlisted. The pipeline row has source sourced and stays hidden from the candidate until they apply themselves. Move shortlisted people on through the pipeline as usual. Do not add a sourced stage to the pipeline rail. The sourcedCandidates methods are deprecated and forward to these calls.

1export async function shortlistOntoJob(
2  accessToken: string,
3  companySlug: string,
4  jobId: string,
5  candidateBoardUserId: string,
6) {
7  const options = session(accessToken);
8  const { data: lists } = await board.me.companies.talentLists.list(
9    companySlug,
10    options,
11  );
12  const jobList =
13    lists.find((list) => list.jobId === jobId) ??
14    (await board.me.companies.talentLists.create(
15      companySlug,
16      { name: 'Shortlist', job: jobId },
17      options,
18    ));
19  return board.me.companies.talentLists.members.add(
20    companySlug,
21    jobList.id,
22    { candidateBoardUserId },
23    options,
24  );
25}

Expected result

An employer sees membership state before any private controls. Approved members can create held drafts, publish or check them out, and read a pipeline whose stages and applicants come from one server response.

Verify the result

A pending or rejected membership cannot edit a company or job.
Claim confirmation produces the membership state shown in the portal.
A created job appears as a draft before publication or checkout.
A free checkout on a board that requires free-job approval returns pending_approval, and the job’s status is pending_approval until the operator approves or rejects it.
Applicant writes re-read the pipeline after the 204 response.
One employer cannot access another company’s private records.

Errors and edge cases

Claiming can approve immediately on a domain match or enter a pending state.
Work-email links expire after 24 hours.
Employer job updates are merge patches; omitted fields remain unchanged.
Remote timezone values auto-derive on create when omitted, but do not re-derive on update.
Custom stages are capped and protected stages cannot be removed or arbitrarily reordered.

Production cautions

Treat applicant data, notes, and signed resume URLs as private.
Keep every employer response out of public caches and logs.
Use the API’s authorization decision even if the UI already hid a control.
Re-read state after void-returning mutations rather than simulating server changes.

Next, add an anonymous purchase path with Job posting and checkout.