Jobs namespace

Reference for job discovery, details, similar jobs, applications, and resume uploads.

Use board.jobs to read published jobs and to run the native application flow. Job discovery and detail reads are public. apply accepts either a candidate session or an allowed guest application, while myApplication requires a candidate session.

Shared behavior

Every method returns the Board API wire body without reshaping it. A non-2xx response throws BoardApiError; inspect status, code, details, and requestId instead of matching the message.

The final FetchOptions argument passes signal, headers, cache, next, cf, and other fetch options through to fetch. List and search results include object, url, hasMore, nextCursor, and data. Job catalog responses can also include count, limit, offset, and gatedCount.

`board.jobs.collectionChoices`

List active entries available to a collection field on the job form. A collection can be shared with company and talent profiles; this method returns choices only for fields configured on jobs.

1board.jobs.collectionChoices(
2  fieldKey: string,
3  query?: { search?: string; cursor?: string; limit?: number },
4  options?: FetchOptions,
5): Promise<JobCollectionChoiceList>

The response contains data entries with id, name, and an optional logoUrl, plus nextCursor. Follow the cursor until it is null. Pass the selected entry IDs when saving collection values through the job posting API. Collection fields on retrieved jobs are available as resolvedCollectionFields; use those resolved names and details for display.

`board.jobs.list`

List published jobs. The default relevance sort uses the board’s featured ranking.

1board.jobs.list(
2  query?: JobsListQuery,
3  options?: FetchOptions,
4): Promise<JobCardListEnvelope>

JobsListQuery accepts:

Field	Type	Behavior
`cursor`	`string`	Opaque `nextCursor` from the previous response.
`limit`	`number`	Page size from 1 to 100.
`offset`	`number`	Jobs to skip. It takes precedence over `cursor`; `offset + limit` cannot exceed 10,000.
`companyId`	`string[]`	Up to 10 company IDs, matched with OR.
`remoteOption`	`RemoteOption[]`	`on_site`, `hybrid`, or `remote`.
`employmentType`	`EmploymentType[]`	Built-in employment types, matched with OR. A built-in matches jobs that have no custom employment type.
`customEmploymentType`	`string[]`	Custom employment type keys from `board.context().jobForm.employmentType.customTypes`, matched with OR and combined with `employmentType`.
`seniority`	`Seniority[]`	Seniority levels, matched with OR.
`sort`	`JobSort`	`relevance`, `newest`, or `salary_high`. An explicit sort unpins featured jobs.
`location`	`string`	Place slug. Returns jobs in the place and the places inside it (a region includes its cities). An unresolvable place is ignored.
`radius`	`number`	Widens a city or locality `location` to jobs whose own city or locality is within this many km of it. 1–250, decimals allowed (`8.05` is 5 mi). Omit it for the place only. Ignored for region and country places and without `location`.
`category`	`string`	Category slug for a programmatic jobs page. An unresolvable category returns 404.
`skill`	`string`	Skill slug for a programmatic jobs page. An unresolvable skill returns 404.
`fields`	`string`	Only `+description` is supported. It adds HTML `description` to each otherwise-slim card.

A location search has no default distance: without radius it returns jobs in the place only. Hosted city pages and the starter apply a default by passing it: 25 mi (about 40.2 km) in miles countries, 50 km elsewhere. Use searchRadiusOptions, defaultSearchRadius, and distanceUnitForCountry from @cavuno/board/format to build the same choices; see Add a search distance to city pages.

The response is JobCardListEnvelope: data contains PublicJobCard values and relatedSearches can suggest category or skill pages. relatedSearches[].count is how many jobs in the returned page carry that term — not the board-wide total. For homepage “browse by category” tiles, use board.taxonomy.categories.list({ sort: 'jobCount' }).

Each card carries customFieldValues for the job and company.customFieldValues for its company, keyed by field key and {} when empty. Cards include only single-select, multi-select, boolean and number values; select values are option keys. Text values are only on the full job and company, and private company fields are never included. Resolve job labels against board.context().customFields.job and company labels against board.profileFields.retrieve('company'). Every method that returns job cards (list, search, similar, company jobs, embed, recommended and saved jobs) uses the same shape.

1const controller = new AbortController();
2const page = await board.jobs.list(
3  {
4    limit: 20,
5    offset: 0,
6    remoteOption: ['remote', 'hybrid'],
7    location: 'london',
8    radius: 25,
9    sort: 'newest',
10  },
11  { signal: controller.signal },
12);
13
14for (const job of page.data) {
15  console.log(job.title, job.links.public);
16}
17
18if (page.hasMore) {
19  console.log('Next cursor:', page.nextCursor);
20}

Handle pagination_invalid_cursor, pagination_offset_too_large, taxonomy not-found errors, and search_unavailable. gatedCount reports jobs hidden from the current viewer; do not present it as another page of accessible results.

Related methods: board.jobs.search, board.companies.listJobs, and paginate.

`board.jobs.retrieve`

Retrieve one published job by slug.

1board.jobs.retrieve(
2  jobSlug: string,
3  query?: Record<string, never>,
4  options?: FetchOptions,
5): Promise<PublicJob>

PublicJob includes job and company identity, description, application URL, employment and salary fields, resolved categories and skills, office locations, place hierarchy, remote-work requirements, custom-field values, and canonical public links. The SDK URL-encodes jobSlug and does not resolve custom-field labels; match customFieldValues keys to board.context().customFields.job. When a job uses one of the board's custom employment types, customEmploymentType is { key, label }: show its label in place of employmentType, which holds its built-in Google equivalent. It is null otherwise.

The country-gated Apply protocol is an explicit starter capability, not a global SDK default. A compatible starter passes this option when retrieving the job and throughout its Apply flow:

1const applyGateway = {
2  headers: {
3    'x-cavuno-board-capabilities': 'apply-gateway-v1',
4  },
5} satisfies FetchOptions;

1const job = await board.jobs.retrieve('senior-engineer', undefined, applyGateway);
2
3console.log(job.title);
4console.log(job.company?.name);
5console.log(job.customFieldValues);

The method returns 404 when the board is unavailable or the slug does not identify a published job. Draft, pending-approval, expired, and archived jobs are not returned by this public read.

Related methods: board.jobs.similar, board.jobs.apply, and board.context for custom-field definitions.

`board.jobs.search`

Search published jobs with free text, facets, date bounds, and geo filters.

1board.jobs.search(
2  body: JobsSearchBody,
3  query?: Record<string, never>,
4  options?: FetchOptions,
5): Promise<JobCardSearchEnvelope>

JobsSearchBody accepts optional query text up to 200 characters, sort, cursor, limit, offset, and filters. Filter arrays accept up to 10 values. filters.publishedAt accepts ISO 8601 gte and lte bounds; filters.location and filters.radius follow the list method’s geo rules.

filters.customFields matches the job's own custom fields (board.context().customFields.job) and filters.companyCustomFields matches the public profile fields of the job's company (board.profileFields.retrieve('company')). Both take CustomFieldFilter clauses of a field key and its accepted values (option keys, booleans, or numbers): clauses are AND-matched and values within one clause are OR-matched, up to 10 clauses of 10 values each. The two lists never share keys, so a job field and a company field may have the same key. An unknown or private key, or an option key the field does not define, returns invalid_filter. See Custom field filters and badges.

1const controller = new AbortController();
2const results = await board.jobs.search(
3  {
4    query: 'platform engineer',
5    sort: 'salary_high',
6    filters: {
7      employmentType: ['full_time'],
8      seniority: ['senior', 'lead'],
9      publishedAt: { gte: '2026-07-01T00:00:00.000Z' },
10    },
11    limit: 20,
12  },
13  undefined,
14  { signal: controller.signal },
15);
16
17console.log(results.data, results.count, results.gatedCount);

This is a POST request, but it is a read operation. Invalid filters or pagination return 400; an unavailable search core returns search_unavailable with status 503.

Related methods: board.jobs.list and board.taxonomy.places.list.

`board.jobs.similar`

Return jobs related to a published job. The result excludes the source job and jobs at the same company.

1board.jobs.similar(
2  jobSlug: string,
3  query?: JobsSimilarQuery,
4  options?: FetchOptions,
5): Promise<ListEnvelope<PublicJobCard>>

query.limit accepts 1–20 and defaults to 5.

1const { data } = await board.jobs.similar('senior-engineer', { limit: 5 });
2
3for (const job of data) {
4  console.log(job.title);
5}

An empty data array is a valid result. A missing source job returns 404; similarity infrastructure failure returns search_unavailable with status 503.

Related methods: board.jobs.retrieve and board.companies.similar.

`board.jobs.apply`

Submit a native application. Signed-in candidates can omit name and email; guests must supply them and can apply only when the board permits guest applications. Repeating the same application is idempotent and returns the existing Application.

1board.jobs.apply(
2  jobSlug: string,
3  body?: ApplyBody,
4  options?: FetchOptions,
5): Promise<Application>

ApplyBody contains optional name, email, and coverNote fields.

1const application = await board.jobs.apply('senior-engineer', {
2  name: 'Avery Chen',
3  email: 'avery@example.com',
4  coverNote: 'I build reliable developer platforms.',
5});
6
7console.log(application.id, application.status);

The returned Application includes its ID, candidate-facing status, timestamps, candidate facts, optional resume filename, and a job summary. Handle applications_guest_not_allowed (403), applications_job_not_found (404), and applications_external_apply_only (422). Use the job’s applicationUrl or the resolveApplyAction helper to branch between native and external apply before submitting.

`board.jobs.prepareApplyApproval`

Prepare the signed-in Candidate's browser-edge country approval for a native job whose applyAction is gateway_native. Call this from the board server with Candidate authorization and a server-owned session key.

1board.jobs.prepareApplyApproval(
2  jobSlug: string,
3  body: { sessionKey: string },
4  options?: FetchOptions,
5): Promise<ApplyApprovalPlan>

The result is either { kind: 'not_required' } or an approval_required plan containing an opaque approvalUrl and expiry. For a required plan, the Candidate browser POSTs directly to that URL with credentials: 'omit' and no body. Pass the returned receipt id and the same key to board.jobs.apply as approvalReceipt and approvalSessionKey.

Pass x-cavuno-board-capabilities: apply-gateway-v1 in options.headers when preparing and when making the final board.jobs.apply call. The SDK does not add this header automatically because doing so would activate the protocol on incompatible boards. This receipt flow is signed-in only; the current starter sends anonymous visitors through sign-in before native preparation, while guest-native API Apply retains its legacy behavior.

`board.jobs.createApplyIntent`

Create a short-lived opaque hand-off for gateway_external. Framework starters call this from a board-local POST and return a browser 303 to the resulting gatewayUrl; never render the gateway URL as a crawlable anchor.

1board.jobs.createApplyIntent(
2  jobSlug: string,
3  body: { sessionKey: string },
4  options?: FetchOptions,
5): Promise<ApplyIntent>

The method accepts no destination. Cavuno resolves the known job's stored destination only after the dedicated gateway allows the request. Pass x-cavuno-board-capabilities: apply-gateway-v1 in options.headers; callers that do not opt in receive the legacy not-found behavior.

1const intent = await board.jobs.createApplyIntent(
2  jobSlug,
3  { sessionKey },
4  applyGateway,
5);

`board.jobs.uploadApplicationResume`

Attach a resume to an existing native application. The SDK creates the multipart FormData body.

1board.jobs.uploadApplicationResume(
2  jobSlug: string,
3  file: Blob,
4  opts?: { applicationId?: string },
5  options?: FetchOptions,
6): Promise<Application>

Signed-in candidates target their own application and omit applicationId. A guest passes the ID returned by board.jobs.apply.

1const application = await board.jobs.apply('senior-engineer', {
2  name: 'Avery Chen',
3  email: 'avery@example.com',
4});
5
6const updated = await board.jobs.uploadApplicationResume(
7  'senior-engineer',
8  resumeFile,
9  { applicationId: application.id },
10);
11
12console.log(updated.resumeFilename);

Empty or malformed files return applications_resume_invalid_file with status 400. Files over 10 MB return 413. Unsupported types or a magic-byte mismatch return 415. A missing or inaccessible application returns applications_not_found with status 404. Do not set content-type yourself; the runtime must add the multipart boundary.

Related method: board.jobs.apply.

`board.jobs.myApplication`

Retrieve the authenticated candidate’s application for one job.

1board.jobs.myApplication(
2  jobSlug: string,
3  options?: FetchOptions,
4): Promise<Application>

1import { isNotFound } from '@cavuno/board';
2
3try {
4  const application = await board.jobs.myApplication('senior-engineer');
5  console.log(application.status);
6} catch (error) {
7  if (isNotFound(error)) {
8    console.log('The candidate has not applied to this job.');
9  } else {
10    throw error;
11  }
12}

This method requires a board-user access token. It returns 401 for a missing, invalid, or expired token; 403 when the token belongs to another board; 404 for a missing board, job, or application; and 429 when the per-user rate limit is exceeded. A 404 application is an expected “not applied” state, not necessarily a broken job page.

Related methods: board.jobs.apply and board.me.applications for the candidate’s full application history.