---
title: "Replace custom job field definitions"
method: PUT
path: "/settings/job-form/custom-fields"
tags: ["Settings"]
---

# Replace custom job field definitions

`PUT /settings/job-form/custom-fields`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/settings/job-form/custom-fields`
- Auth: HTTP bearer

Whole-array replace of the board's custom job field definitions (`jobFormConfig.customFields` only: other job-form keys are untouched). Array order is display order. Empty array removes all fields. Content validation rejects empty labels, duplicate keys, optionless selects, inverted number bounds, and cap breaches (400). Changing `type` on an existing key is rejected (422 `settings_custom_field_type_immutable`); delete the field and recreate it. Renaming a key is delete+add and orphans per-job values under the old key. A field sent without `visibility` keeps its current visibility. The key of a deleted private field cannot be used for a new field (400), so its saved answers stay private. Response shape matches `GET /v1/settings/job-form`.

## Request body

- JobFormCustomFieldsBody
  - `customFields` CustomFieldDefinition[], required: Full replacement list of custom field definitions, in display order. Empty array removes all. Changing `type` on an existing `key` is rejected (422); delete + recreate instead. Renaming a key is delete+add and orphans per-job values under the old key.
    - `key` string, required: Immutable per-board slug used as the key in a job’s `customFieldValues`.
    - `label` string, required: Authoring-default label; the localized public string lives in the board template.
    - `helpText` string: Optional guidance displayed beside the field.
    - `type` 'short_text' | 'long_text' | 'rich_text' | 'single_select' | 'multi_select' | 'boolean' | 'number', required: Field type, which dictates the value: `short_text`/`long_text` → plain string; `rich_text` → sanitized basic HTML; `single_select` → one option key; `multi_select` → array of option keys; `boolean` → boolean; `number` → number.
    - `options` CustomFieldOption[]: Present only for `single_select`/`multi_select`. A stored value is one (or, for multi, several) of these option `key`s — never a label.
      - `key` string, required: Stable option key — the value stored on a job, not the label.
      - `label` string, required: Display label (authoring default; localized per board in the template).
    - `required` boolean, required: When true, the value cannot be cleared or left empty on a write (rejected with `custom_field_required`).
    - `min` number: Inclusive minimum for `number` fields, when set.
    - `max` number: Inclusive maximum for `number` fields, when set.
    - `visibility` 'public' | 'private': Who sees the field. `public` (or absent): the job page, employers, search and the Board API. `private`: only the board team, in the dashboard and this Operator API. Board API (`/v1/boards/...`) responses never include private fields or their values. Omitted on an existing field keeps its current visibility.

## Response `200`

Updated job form configuration (same shape as GET /settings/job-form).

- JobFormConfig
  - `sponsorship` object
    - `visible` boolean, required
  - `salary` object
    - `visible` boolean, required
    - `required` boolean
    - `minBound` number
    - `maxBound` number
    - `allowedCurrencies` string[]
  - `seniority` object
    - `visible` boolean, required
    - `required` boolean
    - `allowedOptions` string[]
  - `workArrangement` object
    - `allowedOptions` string[], required
  - `employmentType` object
    - `allowedOptions` string[], required: Built-in employment types offered. Empty means every built-in, unless the board has custom types: then it means no built-in is offered, only the offered custom types.
    - `customTypes` JobFormCustomEmploymentType[]: The board's custom employment types (at most 20).
      - `key` string, required: Stable key, derived from the name at creation. Send it as `customEmploymentType` on `POST`/`PATCH /v1/jobs`.
      - `label` string, required: Display name, e.g. `Casual`.
      - `employmentType` string, required: The custom type's Google equivalent: a built-in employment type (Google for Jobs and feeds see this value).
      - `offered` boolean: `false` when posters can no longer pick this type (jobs that use it keep its label). Absent means offered.
    - `order` string[]: Display order of built-in values and custom type keys. Absent: built-ins in their standard order, then custom types. Entries it misses follow in that same order.
  - `location` object
    - `visible` boolean, required
    - `allowedCountries` string[]
  - `customFields` CustomFieldDefinition[]: Board-defined custom field definitions, in display order. Read these to learn which `customFieldValues` keys, types, and option keys a job accepts on POST/PATCH /v1/jobs.
    - `key` string, required: Immutable per-board slug used as the key in a job’s `customFieldValues`.
    - `label` string, required: Authoring-default label; the localized public string lives in the board template.
    - `helpText` string: Optional guidance displayed beside the field.
    - `type` 'short_text' | 'long_text' | 'rich_text' | 'single_select' | 'multi_select' | 'boolean' | 'number', required: Field type, which dictates the value: `short_text`/`long_text` → plain string; `rich_text` → sanitized basic HTML; `single_select` → one option key; `multi_select` → array of option keys; `boolean` → boolean; `number` → number.
    - `options` CustomFieldOption[]: Present only for `single_select`/`multi_select`. A stored value is one (or, for multi, several) of these option `key`s — never a label.
      - `key` string, required: Stable option key — the value stored on a job, not the label.
      - `label` string, required: Display label (authoring default; localized per board in the template).
    - `required` boolean, required: When true, the value cannot be cleared or left empty on a write (rejected with `custom_field_required`).
    - `min` number: Inclusive minimum for `number` fields, when set.
    - `max` number: Inclusive maximum for `number` fields, when set.
    - `visibility` 'public' | 'private': Who sees the field. `public` (or absent): the job page, employers, search and the Board API. `private`: only the board team, in the dashboard and this Operator API. Board API (`/v1/boards/...`) responses never include private fields or their values. Omitted on an existing field keeps its current visibility.
  - `collectionFields` JobCollectionFieldDefinition[]: Collection-reference job fields, in display order. Values are stored separately in each job collectionValues bag.
    - `key` string, required
    - `label` string, required
    - `typeId` string, required
    - `multiple` boolean, required
    - `required` boolean, required
    - `maxSelections` integer: Operator-set maximum number of entries a poster can select. Only meaningful when `multiple` is true; absent means the system ceiling of 100.
    - `allowOverrides` boolean: Whether each job can replace a selected entry's title and description through `collectionOverrides`. Absent means false.
    - `descriptionFieldKey` string: Key of the collection's short, long or rich text field whose value is a selected entry's default description. When that field is rich text, an entry's `description` is sanitised HTML. Absent means entries have no default description.
    - `visibility` 'public' | 'private': Who sees the field. `public` (or absent): the job page, employers, search and the Board API. `private`: only the board team, in the dashboard and this Operator API. Board API (`/v1/boards/...`) responses never include private fields or their values. Omitted on an existing field keeps its current visibility.

## Other responses

- `400`: Content validation failed (duplicate keys, optionless select, etc.).
- `422`: Attempted to change `type` on an existing custom field key.

## Changes

- **2026-10-19** `c34152c38176`: 2 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 `422` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/settings/job-form/custom-fields/put.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)