Applications

Build guest and signed-in apply flows, resume upload, history, editing, and withdrawal.

Build a native application flow without hard-coding one universal form. Cavuno decides whether guests may apply and validates the live requirements; your frontend collects the values and renders the returned application state.

Prerequisites

A published job loaded with board.jobs.retrieve.
Candidate sessions if the board requires sign-in.
A file input if you accept application resumes.

board.jobs.apply supports optional authentication. A signed-in candidate may omit name and email; a guest supplies them.

Submit an application

1// src/data/applications.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
13function capableSession(accessToken: string): FetchOptions {
14  return {
15    cache: 'no-store',
16    headers: {
17      authorization: `Bearer ${accessToken}`,
18      'x-cavuno-board-capabilities': 'apply-gateway-v1',
19    },
20  };
21}
22
23export async function applyAsGuest(
24  jobSlug: string,
25  input: { name: string; email: string; coverNote?: string; resume?: Blob },
26) {
27  const application = await board.jobs.apply(jobSlug, {
28    name: input.name,
29    email: input.email,
30    coverNote: input.coverNote,
31  });
32
33  if (!input.resume) return application;
34
35  return board.jobs.uploadApplicationResume(jobSlug, input.resume, {
36    applicationId: application.id,
37  });
38}
39
40export async function applyAsCandidate(
41  accessToken: string,
42  jobSlug: string,
43  coverNote?: string,
44) {
45  return board.jobs.apply(
46    jobSlug,
47    { coverNote },
48    session(accessToken),
49  );
50}

Apply is idempotent: a repeated submission returns the existing application. Do not show a second success state or create a local duplicate.

Handle country-gated native Apply

When a capable starter receives applyAction: 'gateway_native', prepare the signed-in Candidate's approval from your server with board.jobs.prepareApplyApproval. Keep its sessionKey in an HTTP-only board cookie; do not derive it from Profile data.

Load the job with x-cavuno-board-capabilities: apply-gateway-v1 in options.headers, and send the same capability on preparation and final Apply. The SDK deliberately does not add this header globally: it is an opt-in for starters that implement the complete browser-edge protocol.

The native receipt protocol is for signed-in Candidates. The current starter sends an anonymous visitor through sign-in before preparing gateway_native; guest-native API submissions retain the legacy behavior and are not country-gated by this protocol.

If the plan is approval_required, have the Candidate browser POST directly to approvalUrl with credentials: 'omit' and no body. The exact board origin is checked by Cavuno. Submit the returned receipt ID and the same server-owned key with the native application:

1const plan = await board.jobs.prepareApplyApproval(
2  jobSlug,
3  { sessionKey },
4  capableSession(accessToken),
5);
6
7let approvalReceipt: string | undefined;
8if (plan.kind === 'approval_required') {
9  const response = await fetch(plan.approvalUrl, {
10    method: 'POST',
11    credentials: 'omit',
12  });
13  if (!response.ok) throw new Error('Apply is unavailable from this location');
14  approvalReceipt = (await response.json()).id;
15}
16
17await board.jobs.apply(
18  jobSlug,
19  { coverNote, approvalReceipt, approvalSessionKey: sessionKey },
20  capableSession(accessToken),
21);

Do not send a country, IP, forwarding header, cookies, or an application body to approvalUrl. If the plan is not_required, continue with the ordinary native submission.

Build application history

1export async function loadApplications(accessToken: string) {
2  return board.me.applications.list(
3    { limit: 20 },
4    session(accessToken),
5  );
6}
7
8export async function editApplication(
9  accessToken: string,
10  applicationId: string,
11  coverNote: string,
12) {
13  return board.me.applications.updateFacts(
14    applicationId,
15    { coverNote },
16    session(accessToken),
17  );
18}
19
20export async function withdrawApplication(
21  accessToken: string,
22  applicationId: string,
23) {
24  await board.me.applications.withdraw(
25    applicationId,
26    session(accessToken),
27  );
28}

withdraw resolves with no body after the permanent deletion succeeds. Remove the row only after the promise resolves.

Expected result

A successful submission returns one Application with its server-owned status and facts. Signed-in history returns only the viewer’s applications; a completed withdrawal returns no response body.

Verify the result

A guest application includes the returned id, status, and candidate facts.
Resume upload uses the guest application.id; signed-in uploads do not need it.
A repeat apply converges on the existing application.
History lists only the signed-in candidate’s applications.
Editing or withdrawing another user’s application is rejected by the API.

Errors and edge cases

A board can require authentication even though the method accepts a guest body.
Resume upload uses multipart data. Pass a Blob; do not JSON-encode the file.
myApplication(jobSlug) throws a typed 404 when the signed-in candidate has not applied.
Candidate facts are editable only while the application remains editable.
Employer review belongs to board.me.companies.applicants, behind an employer session.

Production cautions

Disable the submit control while a request is in flight, but rely on server idempotency for retries.
Do not log resumes, cover notes, names, or email addresses.
Keep candidate and employer authorization paths separate.
Display server-returned status values rather than maintaining a parallel client workflow.

Next, add recurring discovery with Job alerts.