Cavuno
Sign InStart for free

Embed namespace

Reference for the embeddable jobs response.

Abi Tyas TunggalAJack WalshJ
By Abi Tyas Tunggal and Jack Walsh

Use board.embed.jobs to load compact published-job cards for the public “Powered by Cavuno” embed. The candidate paywall does not gate this response, but board password protection and plan API access still apply.

Shared behavior

The method returns the Board API wire body unchanged and throws BoardApiError for a non-2xx response. Its trailing FetchOptions passes abort signals, headers, and framework cache directives through to fetch.

board.embed.jobs

FieldTypeBehavior
qstringFree-text query up to 200 characters.
cursorstringOpaque cursor from nextCursor.
limitnumberDefaults to 8; values above 50 are clamped to 50.
offsetnumberJobs to skip. It takes precedence over cursor; offset + limit cannot exceed 10,000.
companyIdstring[]Up to 10 company IDs, matched with OR.
remoteOptionRemoteOption[]on_site, hybrid, or remote.
employmentTypeEmploymentType[]Built-in employment types, matched with OR. A built-in matches jobs that have no custom employment type.
customEmploymentTypestring[]Custom employment type keys from board.context().jobForm.employmentType.customTypes, matched with OR and combined with employmentType.
senioritySeniority[]Seniority levels, matched with OR.
locationstringPlace slug. Returns jobs in the place and the places inside it (a region includes its cities). An unresolvable place is ignored.
radiusnumberWidens 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.

The response contains object: 'list', url, hasMore, nextCursor, data, and the catalog count, limit, and offset fields when supplied by the API. Each PublicJobCard contains the fields needed for a listing card: identity, title/slug, publish date, employment and remote details, salary, company, categories, skills, the job's and company's select, boolean and number custom-field values, and canonical link.

Gating and edge behavior

The embed deliberately does not return gatedCount or relatedSearches: candidate-paywall gating and the main job list’s related-search rail do not apply. Do not infer candidate entitlement from the embed response.

Handle:

  • pagination_invalid_cursor or pagination_offset_too_large with status 400.
  • board_password_required with status 401; obtain a board access grant through board.password.verify before retrying.
  • plan_upgrade_required with status 402 when the board plan does not include API access.
  • A missing/private board with status 404.
  • search_unavailable with status 503.

Abort superseded interactive searches with FetchOptions.signal. Use nextCursor only when hasMore is true; an empty data array is a successful result.

  • Use board.jobs.list for the board’s normal candidate-facing catalog, including paywall counts and related searches.
  • Use board.jobs.retrieve for the canonical job detail after a user follows a card link.
  • Use board.password.verify when a password-protected board returns board_password_required.