--- title: "Update board settings" method: PATCH path: "/settings" tags: ["Settings"] --- # Update board settings `PATCH /settings` ## Request - Base URL: `https://api.cavuno.com/v1` - URL: `https://api.cavuno.com/v1/settings` - Auth: HTTP bearer Updates typed board settings by setting the values supplied. Omitted values remain unchanged; settings outside this allowlist use their dedicated product endpoint. ## Request body - PatchSettingsBody - `name` string: Display name of the board. - `slug` string: URL slug of the board. Lowercase alphanumeric and hyphens; reserved values (e.g. `admin`, `api`) are rejected. - `primaryDomainId` string: Identifier of the custom domain to use as the primary public URL. - `logoMediaId` string: Cavuno media ID returned by `POST /v1/media/upload` with `purpose=board_logo`. - `heroMediaId` string: Cavuno media ID returned by `POST /v1/media/upload` with `purpose=board_hero`. - `passwordProtectionEnabled` boolean: Whether the board sits behind a password gate. Use `POST /v1/settings/password-protection` to set the actual password before enabling. - `jobAlertsEnabled` boolean: Whether candidates can subscribe to email alerts for new jobs. - `jobRecommendationsEnabled` boolean: Whether signed-in candidates can see personalized job recommendations. Absent board config defaults to `true`. - `recommendedTalentEnabled` boolean: Whether employers can see recommended talent matches for their jobs. Absent board config defaults to `false`. - `candidatesEnabled` boolean: Whether candidate profiles are enabled on the board. - `employersEnabled` boolean: Whether employer self-serve flows are enabled. - `blogEnabled` boolean: Whether the public blog is exposed. - `impressumEnabled` boolean: Whether the legal Impressum page is exposed (required in some jurisdictions). - `requireApprovalFreeJobs` boolean: Whether jobs posted by employers from the free tier require admin approval before they appear on the public board. - `postingRequiresMembership` boolean: When true, only companies with an active plan assignment can post jobs. Absent means anyone can post. - `requireApprovalAggregatedJobs` boolean: Whether aggregated jobs (e.g. those sourced or imported from upstream sources) require admin approval before they appear on the public board. - `registrationWallEnabled` boolean: Whether visitors must sign in to view jobs. - `nativeApplicationsEnabled` boolean: Whether the board's built-in ATS receives applications. When `false` (external-applications-only board), posting surfaces require an external `applicationUrl` and `POST /boards/:identifier/jobs/:jobSlug/apply` rejects with `applications_native_disabled`. Turning this off UNPUBLISHES every published native-apply job (those with no external `applicationUrl`) back to draft via an asynchronous batched drain. Expect published job counts to shrink over the following seconds. Nothing is deleted, and re-enabling does NOT republish the drafted jobs. Absent means `true`. - `countryGatingMode` 'sponsored_only' | 'all_jobs': Apply country gate mode. The default is sponsored_only; all_jobs also gates ordinary external and native starter applies. - `applicantMessagingEnabled` boolean: Whether applicant↔employer messaging is enabled. When `false`, the `me/conversations` route family rejects with `messaging_disabled` and new-message emails are suppressed. Absent means `true`. - `applyUrlAttribution` union - object: Query parameters appended to outbound apply URLs. `{ "mode": "off" }` appends nothing — use it for boards whose upstream application host rejects unexpected query parameters. `{ "mode": "append", "params": [...] }` sets the parameters explicitly; each `valueTemplate` may contain the `{{boardHost}}`, `{{boardSlug}}` and `{{boardName}}` tokens. An `append` policy with an empty `params` array is stored as `off`. Absent board config means the default `ref={{boardHost}}`. Individual import feeds can override this per feed. - `mode` 'off', required - object: Query parameters appended to outbound apply URLs. `{ "mode": "off" }` appends nothing — use it for boards whose upstream application host rejects unexpected query parameters. `{ "mode": "append", "params": [...] }` sets the parameters explicitly; each `valueTemplate` may contain the `{{boardHost}}`, `{{boardSlug}}` and `{{boardName}}` tokens. An `append` policy with an empty `params` array is stored as `off`. Absent board config means the default `ref={{boardHost}}`. Individual import feeds can override this per feed. - `mode` 'append', required - `params` ApplyUrlParamTemplate[], required - `key` string, required - `valueTemplate` string, required - `talentDirectoryEnabled` boolean: Legacy shorthand for the talent directory. `true` maps to `talentDirectoryVisibility: "public"`; `false` maps to `"off"`. Prefer the tri-state field. Providing both with conflicting values returns `settings_conflicting_fields`. - `talentDirectoryVisibility` 'off' | 'public' | 'employers_only': Talent directory access mode: `off` (hidden), `public` (anyone), or `employers_only` (approved employers). Canonical field; supersedes `talentDirectoryEnabled`. - `defaultCandidateProfileVisibility` 'hidden' | 'logged_in_only' | 'public': Visibility a candidate profile is created with at signup: `hidden` (not listed), `logged_in_only` (signed-in visitors), or `public`. Defaults to `hidden`, which matches what an unset value already means — the talent directory lists only `public` and `logged_in_only` profiles. Applies at signup ONLY: it never rewrites an existing profile, and a candidate can change their own afterwards. Composes with `talentDirectoryVisibility`, which controls who may browse the directory at all. - `requireCookieConsent` boolean: Whether the public board shows a cookie consent banner before non-essential tracking runs. - `cookieBannerTitle` string: Title shown on the cookie consent banner. 1–200 characters. - `cookieBannerDescription` string: Body copy shown on the cookie consent banner. 1–500 characters. - `cookieBannerRejectLabel` string: Reject-button label on the cookie consent banner. 1–80 characters. - `cookieBannerAcceptLabel` string: Accept-button label on the cookie consent banner. 1–80 characters. - `cookieBannerManageLabel` string: Preferences/manage-button label on the cookie consent banner. 1–80 characters. - `showCavunoBranding` boolean: Whether the Cavuno-branded footer is displayed on the public board. Plan-gated; lower-tier plans cannot disable this. - `defaultJobDurationDays` integer: Default expiry, in days, applied to newly published jobs when no `expiresAt` is supplied. - `contactEmail` union: Public contact email shown on the board. Pass `null` to clear. - string, email - '' - unknown - `companyLegalName` union: Legal name of the entity operating the board. Pass `null` to clear. - string - '' - unknown - `companyAddress` union: Postal address of the entity operating the board. Pass `null` to clear. - string - '' - unknown - `companyWebsiteUrl` union: Public company website URL. Pass `null` to clear. - string - '' - unknown - `companyXHandle` union: Company X (Twitter) handle or profile URL. Pass `null` to clear. - string - '' - unknown - `companyFacebookUrl` union: Company Facebook page URL. Pass `null` to clear. - string - '' - unknown - `companyLinkedinUrl` union: Company LinkedIn page URL. Pass `null` to clear. - string - '' - unknown - `companyInstagramUrl` union: Company Instagram handle or profile URL. Pass `null` to clear. - string - '' - unknown - `ga4MeasurementId` string, nullable: Google Analytics 4 measurement ID (for example `G-XXXXXXXXXX`) loaded on the public board. Letters, digits, `-` and `_`, up to 120 characters. Pass `null` or an empty string to clear. - `gtmContainerId` string, nullable: Google Tag Manager container ID (for example `GTM-XXXXXXX`) loaded on the public board. Letters, digits, `-` and `_`, up to 120 characters. Pass `null` or an empty string to clear. - `metaPixelId` string, nullable: Meta Pixel ID loaded on the public board. Letters, digits, `-` and `_`, up to 120 characters. Pass `null` or an empty string to clear. - `linkedinPartnerId` string, nullable: LinkedIn Insight Tag partner ID loaded on the public board. Letters, digits, `-` and `_`, up to 120 characters. Pass `null` or an empty string to clear. - `linkedinConversionSignUpId` string, nullable: LinkedIn conversion ID fired when a visitor signs up. Letters, digits, `-` and `_`, up to 120 characters. Pass `null` or an empty string to clear. - `linkedinConversionLoginId` string, nullable: LinkedIn conversion ID fired when a visitor signs in. Letters, digits, `-` and `_`, up to 120 characters. Pass `null` or an empty string to clear. - `linkedinConversionApplyClickId` string, nullable: LinkedIn conversion ID fired when a visitor clicks Apply. Letters, digits, `-` and `_`, up to 120 characters. Pass `null` or an empty string to clear. - `linkedinConversionApplySubmitId` string, nullable: LinkedIn conversion ID fired when a visitor submits an application. Letters, digits, `-` and `_`, up to 120 characters. Pass `null` or an empty string to clear. - `linkedinConversionJobAlertSubscribeId` string, nullable: LinkedIn conversion ID fired when a visitor subscribes to job alerts. Letters, digits, `-` and `_`, up to 120 characters. Pass `null` or an empty string to clear. - `talentNavLabel` string: Label shown for the talent directory in the public navigation. 1–50 characters. - `passwordProtectionMessage` union: Deprecated: no longer shown on the password gate. Gate copy now lives on the board's builder-designed coming-soon page. Still accepted and returned for compatibility; it will be removed with the hosted board. Up to 500 characters. Pass `null` to clear. - string - '' - unknown - `signInMethods` SignInMethodsPatch: Switch built-in sign-in methods on or off per role; omitted methods stay as they are. Switching off a role’s last way to sign in (no other built-in method on, and no tested SSO connection switched on for that role) is refused with 409 `sign_in_method_last`. People already signed in stay signed in. - `candidate` object - `password` boolean - `magicLink` boolean - `google` boolean - `linkedin` boolean - `employer` object - `password` boolean - `magicLink` boolean - `google` boolean - `linkedin` boolean ## Response `200` Successful response. - Settings - `id` string, required - `object` 'settings', required - `accountId` string, required - `name` string, required - `slug` string, required - `primaryDomainId` string, nullable, required - `logoUrl` string, nullable, required - `heroUrl` string, nullable, required - `config` OperatorSettingsConfig, required - `passwordProtectionEnabled` boolean - `jobAlertsEnabled` boolean - `jobRecommendationsEnabled` boolean, required - `recommendedTalentEnabled` boolean, required - `candidatesEnabled` boolean - `employersEnabled` boolean - `blogEnabled` boolean - `impressumEnabled` boolean - `requireApprovalFreeJobs` boolean - `postingRequiresMembership` boolean - `requireApprovalAggregatedJobs` boolean - `registrationWallEnabled` boolean - `nativeApplicationsEnabled` boolean - `countryGatingMode` 'sponsored_only' | 'all_jobs': Apply country gate mode. sponsored_only is the minimum mode for Sponsored inventory. - `applicantMessagingEnabled` boolean - `applyUrlAttribution` union: Query parameters appended to outbound apply URLs. Absent means the default `ref={{boardHost}}`. - object - `mode` 'off', required - object - `mode` 'append', required - `params` ApplyUrlParamTemplate[], required - `key` string, required - `valueTemplate` string, required - `requireCookieConsent` boolean - `showCavunoBranding` boolean - `cookieBannerTitle` string - `cookieBannerDescription` string - `cookieBannerRejectLabel` string - `cookieBannerAcceptLabel` string - `cookieBannerManageLabel` string - `talentNavLabel` string - `contactEmail` string, nullable - `companyLegalName` string, nullable - `companyAddress` string, nullable - `companyWebsiteUrl` string, nullable - `companyXHandle` string, nullable - `companyFacebookUrl` string, nullable - `companyLinkedinUrl` string, nullable - `companyInstagramUrl` string, nullable - `ga4MeasurementId` string, nullable - `gtmContainerId` string, nullable - `metaPixelId` string, nullable - `linkedinPartnerId` string, nullable - `linkedinConversionSignUpId` string, nullable - `linkedinConversionLoginId` string, nullable - `linkedinConversionApplyClickId` string, nullable - `linkedinConversionApplySubmitId` string, nullable - `linkedinConversionJobAlertSubscribeId` string, nullable - `passwordProtectionMessage` string, nullable: Deprecated: no longer shown on the password gate. Gate copy now lives on the board's builder-designed coming-soon page. Still accepted and returned for compatibility; it will be removed with the hosted board. - `defaultJobDurationDays` integer - `talentDirectoryVisibility` 'off' | 'public' | 'employers_only' - `defaultCandidateProfileVisibility` 'hidden' | 'logged_in_only' | 'public' - `signInMethods` SignInMethods, required: Which built-in sign-in methods are switched on for candidates and for employers. SSO connections are switched on per role on `/sso-connections`. - `candidate` BuiltInSignInMethods, required - `password` boolean, required: Email and password. - `magicLink` boolean, required: Emailed one-time sign-in link. - `google` boolean, required: Sign in with Google. - `linkedin` boolean, required: Sign in with LinkedIn. - `employer` BuiltInSignInMethods, required - `password` boolean, required: Email and password. - `magicLink` boolean, required: Emailed one-time sign-in link. - `google` boolean, required: Sign in with Google. - `linkedin` boolean, required: Sign in with LinkedIn. - `createdAt` string, required - `updatedAt` string, required ## Other responses - `400`: The request was malformed. - `403`: The account's plan tier does not permit this change. Common cases include disabling password protection on a plan that requires it, and removing Cavuno branding on a plan that does not allow it. - `409`: The supplied slug is already in use, or password protection cannot be enabled until a password is set via `POST /v1/settings/password-protection`. ## Changes - **2026-10-20** `de39bd3242e2`: 18 info - added the new optional request property `ga4MeasurementId` - added the new optional request property `gtmContainerId` - added the new optional request property `linkedinConversionApplyClickId` - added the new optional request property `linkedinConversionApplySubmitId` - …14 more - **2026-10-19** `c34152c38176`: 3 info - added the optional property `error/upgrade` to the response with the `400` status - added the optional property `error/upgrade` to the response with the `403` status - added the optional property `error/upgrade` to the response with the `409` status [Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/settings/patch.md) --- [API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)