---
title: "Replace form layouts"
method: PUT
path: "/settings/form-layouts"
tags: ["Settings"]
---

# Replace form layouts

`PUT /settings/form-layouts`

## Request

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

Replaces one or more of the job, company and talent form layouts. Each supplied list is the full ordered form; any field it leaves out is appended in the default order. The job form also updates the matching job form settings (salary and seniority visible and required, location visible). Rejected with 400 `validation_bad_request` for unknown or duplicate keys, a hidden or optional locked built-in, required on a hidden or non-requirable built-in, a hidden field whose definition is required, and any Google for Jobs rule; `error.details.issues` lists each problem as `{ form, code, key, message }`. Nothing is written unless every supplied list is valid. Requires `settings.manage`.

## Request body

- ReplaceFormLayoutsBody
  - `job` FormLayoutFieldRef[]: The job form, in display order.
    - union
      - FormLayoutBuiltinFieldRef
        - `kind` 'builtin', required
        - `key` string, required: The built-in field key. Job: `employmentType`, `seniority`, `title`, `workArrangement`, `location`, `remoteEligibility`, `description`, `salary`, `applyMethod`, `company`. Company: `name`, `website`, `summary`, `xUrl`, `linkedinUrl`, `facebookUrl`, `logo`, `description`. Talent: `name`, `email`, `avatar`, `headline`, `location`, `jobSearchStatus`, `bio`, `experience`, `education`, `skills`, `languages`. New built-ins may be added; skip keys you do not recognise.
        - `visible` boolean, required: Whether the form shows the field.
        - `required` boolean, required: Whether a submission must fill the field. Only a shown, requirable built-in can be required; a locked built-in must stay shown and required.
      - FormLayoutCustomFieldRef
        - `kind` 'custom', required
        - `key` string, required: An existing custom field key on this form.
        - `visible` boolean: Set `false` to hide the field; absent means shown. A field whose definition is required cannot be hidden: unset its `required` flag first.
      - FormLayoutCollectionFieldRef
        - `kind` 'collection', required
        - `key` string, required: An existing collection reference key on this form.
        - `visible` boolean: Set `false` to hide the field; absent means shown. A field whose definition is required cannot be hidden: unset its `required` flag first.
  - `company` FormLayoutFieldRef[]: The company profile form, in display order.
    - union
      - FormLayoutBuiltinFieldRef
        - `kind` 'builtin', required
        - `key` string, required: The built-in field key. Job: `employmentType`, `seniority`, `title`, `workArrangement`, `location`, `remoteEligibility`, `description`, `salary`, `applyMethod`, `company`. Company: `name`, `website`, `summary`, `xUrl`, `linkedinUrl`, `facebookUrl`, `logo`, `description`. Talent: `name`, `email`, `avatar`, `headline`, `location`, `jobSearchStatus`, `bio`, `experience`, `education`, `skills`, `languages`. New built-ins may be added; skip keys you do not recognise.
        - `visible` boolean, required: Whether the form shows the field.
        - `required` boolean, required: Whether a submission must fill the field. Only a shown, requirable built-in can be required; a locked built-in must stay shown and required.
      - FormLayoutCustomFieldRef
        - `kind` 'custom', required
        - `key` string, required: An existing custom field key on this form.
        - `visible` boolean: Set `false` to hide the field; absent means shown. A field whose definition is required cannot be hidden: unset its `required` flag first.
      - FormLayoutCollectionFieldRef
        - `kind` 'collection', required
        - `key` string, required: An existing collection reference key on this form.
        - `visible` boolean: Set `false` to hide the field; absent means shown. A field whose definition is required cannot be hidden: unset its `required` flag first.
  - `talent` FormLayoutFieldRef[]: The talent (candidate) profile form, in display order.
    - union
      - FormLayoutBuiltinFieldRef
        - `kind` 'builtin', required
        - `key` string, required: The built-in field key. Job: `employmentType`, `seniority`, `title`, `workArrangement`, `location`, `remoteEligibility`, `description`, `salary`, `applyMethod`, `company`. Company: `name`, `website`, `summary`, `xUrl`, `linkedinUrl`, `facebookUrl`, `logo`, `description`. Talent: `name`, `email`, `avatar`, `headline`, `location`, `jobSearchStatus`, `bio`, `experience`, `education`, `skills`, `languages`. New built-ins may be added; skip keys you do not recognise.
        - `visible` boolean, required: Whether the form shows the field.
        - `required` boolean, required: Whether a submission must fill the field. Only a shown, requirable built-in can be required; a locked built-in must stay shown and required.
      - FormLayoutCustomFieldRef
        - `kind` 'custom', required
        - `key` string, required: An existing custom field key on this form.
        - `visible` boolean: Set `false` to hide the field; absent means shown. A field whose definition is required cannot be hidden: unset its `required` flag first.
      - FormLayoutCollectionFieldRef
        - `kind` 'collection', required
        - `key` string, required: An existing collection reference key on this form.
        - `visible` boolean: Set `false` to hide the field; absent means shown. A field whose definition is required cannot be hidden: unset its `required` flag first.

## Response `200`

The three form layouts after the write.

- FormLayouts: The job, company and talent forms as resolved, ordered field lists: every built-in, custom field and collection reference, including private profile fields. Fields never placed by an operator follow in the default order.
  - `job` FormLayoutField[], required
    - `kind` 'builtin' | 'custom' | 'collection', required: A built-in field, a custom field, or a collection reference.
    - `key` string, required
    - `label` string, required: The field label shown in Settings.
    - `visible` boolean, required: Whether the form shows the field.
    - `required` boolean, required: Whether a submission must fill the field. Always `false` for a hidden field.
    - `locked` boolean, required: A locked built-in can move but must stay shown and required. Always `false` for custom and collection fields.
    - `lockReason` 'google_required' | 'google_hiring_organization' | 'google_work_arrangement' | 'google_job_location' | 'google_remote_eligibility' | 'posting' | 'identity', nullable, required: Why the field is locked, or `null`.
    - `requirable` boolean, required: Whether a layout write can switch `required` on. Custom and collection fields take `required` from their own definition (the job-form custom-fields and profile-field endpoints), so they are never requirable here.
  - `company` FormLayoutField[], required
    - `kind` 'builtin' | 'custom' | 'collection', required: A built-in field, a custom field, or a collection reference.
    - `key` string, required
    - `label` string, required: The field label shown in Settings.
    - `visible` boolean, required: Whether the form shows the field.
    - `required` boolean, required: Whether a submission must fill the field. Always `false` for a hidden field.
    - `locked` boolean, required: A locked built-in can move but must stay shown and required. Always `false` for custom and collection fields.
    - `lockReason` 'google_required' | 'google_hiring_organization' | 'google_work_arrangement' | 'google_job_location' | 'google_remote_eligibility' | 'posting' | 'identity', nullable, required: Why the field is locked, or `null`.
    - `requirable` boolean, required: Whether a layout write can switch `required` on. Custom and collection fields take `required` from their own definition (the job-form custom-fields and profile-field endpoints), so they are never requirable here.
  - `talent` FormLayoutField[], required
    - `kind` 'builtin' | 'custom' | 'collection', required: A built-in field, a custom field, or a collection reference.
    - `key` string, required
    - `label` string, required: The field label shown in Settings.
    - `visible` boolean, required: Whether the form shows the field.
    - `required` boolean, required: Whether a submission must fill the field. Always `false` for a hidden field.
    - `locked` boolean, required: A locked built-in can move but must stay shown and required. Always `false` for custom and collection fields.
    - `lockReason` 'google_required' | 'google_hiring_organization' | 'google_work_arrangement' | 'google_job_location' | 'google_remote_eligibility' | 'posting' | 'identity', nullable, required: Why the field is locked, or `null`.
    - `requirable` boolean, required: Whether a layout write can switch `required` on. Custom and collection fields take `required` from their own definition (the job-form custom-fields and profile-field endpoints), so they are never requirable here.

## Other responses

- `400`: A layout was rejected. `error.details.issues` names each offending field.

## Changes

- **2026-10-20** `d5974dabff14`: 3 breaking, 24 info
  - the `company/items/lockReason` response's property type changed from `string` to no type for status `200`
  - the `job/items/lockReason` response's property type changed from `string` to no type for status `200`
  - the `talent/items/lockReason` response's property type changed from `string` to no type for status `200`
  - added `#/components/schemas/FormFieldLockReason, subschema #2` to the `company/items/lockReason` response property `allOf` list for the response status `200`
  - …23 more
- **2026-10-20** `cee1c2d567e5`: 6 breaking, 21 warning, 3 info
  - the response property `company/items/lockReason` became nullable for the status `200`
  - the response property `job/items/lockReason` became nullable for the status `200`
  - the response property `talent/items/lockReason` became nullable for the status `200`
  - the `company/items/lockReason` response's property type changed from no type to `string` for status `200`
  - …26 more
- …earlier changes not shown

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