---
title: "Retrieve the job form configuration"
method: GET
path: "/settings/job-form"
tags: ["Settings"]
---

# Retrieve the job form configuration

`GET /settings/job-form`

## Request

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

Retrieves the board's job form configuration: built-in field tuning plus any custom field definitions. Read this before writing custom-field values: each definition's `key`, `type`, and `options` tell you what to send in the `customFieldValues` object on `POST`/`PATCH /v1/jobs`. Returns an empty object when the board has not configured it.

## Response `200`

Successful response.

- 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

- `default`: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.

## Changes

- **2026-10-19** `c34152c38176`: 1 info
  - added the optional property `error/upgrade` to the response with the `default` status

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