---
title: "Update custom field"
method: PATCH
path: "/v3/custom_fields/{id}"
tags: ["Custom Fields"]
---

# Update custom field

`PATCH /v3/custom_fields/{id}`

Edit the definition of an existing custom field. `field_type` and `value_type` are immutable — to change either, create a new field. As with create, the accepted properties vary by the field's existing `field_type`: job and opening fields expose approval and visibility toggles, offer fields expose `trigger_new_version`, user attributes are limited to `name`, `description`, and `required`. Manage option lists for select-type fields through `/v3/custom_field_options`, not this endpoint.

## Path parameters

- `id` integer, required

## Request body

- object
  - `name` string — New display label for the field. Renaming does not change `name_key` — integrations keyed off `name_key` continue working.
  - `description` string — New helper text shown beneath the field label in the UI.
  - `private` boolean — If `true`, only users granted the matching `View Private` permission can see this field's values.
  - `template_token_string` string — Updated merge token usable in offer letter templates.

## Response `200`

Successful

- object
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `field_type` 'job' | 'opening' | 'standard' | 'offer' | 'compensation_frequency' | 'candidate' | 'referral_question' | 'application' | 'rejection_question' | 'form' | 'agency_question' | 'user_attribute' — Resource this field attaches to. Drives which create/update request shape applies and which endpoints accept the field as a `custom_fields` value (e.g. `job` fields appear on `/v3/jobs`, `candidate` fields on `/v3/candidates`).
  - `sort_order` integer — Display priority within the field group on this `field_type`. Lower values render first; alias of `priority` in V1/V2.
  - `name` string — Human-readable label shown to recruiters and hiring managers (e.g. `Cost Center`, `Start Date`). Unique among active fields of the same `field_type`.
  - `value_type` 'short_text' | 'long_text' | 'yes_no' | 'single_select' | 'multi_select' | 'currency' | 'number' | 'date' | 'url' | 'currency_range' | 'number_range' | 'user' | 'linked' | 'header' | 'statement' | 'attachment' | 'rich_text' — Data type and editor. `short_text`, `long_text`, `yes_no`, `single_select`, `multi_select`, `currency`, `currency_range`, `number`, `number_range`, `date`, `url`, `user`, `attachment`, `rich_text`, and the `*_hris` masked-PII variants. Only `single_select` and `multi_select` carry options — fetch them from `/v3/custom_field_options?custom_field_ids={id}`.
  - `private` boolean — If `true`, only users granted the matching `View Private` permission can see or edit this field's values.
  - `required` boolean — If `true`, a value must be supplied before the parent resource (job, offer, application, etc.) can be saved through the UI. The API still accepts blank values; enforcement happens at the form layer.
  - `require_approval` boolean — Job and opening fields only. If `true`, edits to this field's value route through the job's approval workflow before taking effect.
  - `trigger_new_version` boolean — Offer fields only. If `true`, changing this field's value on an existing offer creates a new offer version rather than mutating the current one in place.
  - `active` boolean, nullable — `true` when the field is in use; `false` after archival. Archived fields are still returned by default — pass `active=true` on `/v3/custom_fields` to filter to live fields only.
  - `updated_by_id` integer, nullable — Id of the Greenhouse user who last edited the field definition, or `null` if no edit has been recorded.
  - `internal_type` 'employment_type' | 'offer_documents' | 'start_date' | 'school_name' | 'degree' | 'discipline' | 'offer_opening' | 'null', nullable — Greenhouse-managed semantic role for system-supplied fields (`employment_type`, `offer_documents`, `start_date`, `school_name`, `degree`, `discipline`, `offer_opening`). `null` for org-defined custom fields.
  - `expose_in_job_board_api` boolean — Job fields only. If `true`, the field's value is exposed on the public Job Board API alongside the job listing.
  - `placeholder` string, nullable — Greyed-out hint text shown inside an empty field input in the UI.
  - `name_key` string — Stable lowercase identifier derived from `name` (e.g. `Cost Center` → `cost_center`). Use this — not `id` — as the canonical key when setting values via `custom_fields` on `/v3/jobs`, `/v3/offers`, `/v3/candidates`, and similar write endpoints.
  - `description` string, nullable — Helper text shown beneath the field label in the UI. Plain text, no markup.
  - `application_type` 'all_applications' | 'candidate_applications' | 'prospect_applications' | 'null', nullable — Application fields only. Restricts which applications the field appears on: `all_applications`, `candidate_applications` (applicants), or `prospect_applications`. `null` for non-application fields.
  - `api_only` boolean, nullable — Job fields only. If `true`, the field can only be edited through Harvest API calls — the UI renders it read-only. Mutually exclusive with `required`.
  - `use_for_job_approvals` boolean, nullable — Job fields only. If `true`, the field is included on the job-approval form so approvers see its value when reviewing the job.
  - `use_for_offer_approvals` boolean, nullable — Job fields only. If `true`, the field's value flows onto the offer-approval form for jobs that route offers through approvals.
  - `template_token_string` string, nullable — Merge token usable in offer letter templates (e.g. `{{CUSTOM_FIELD_NAME}}`). Returned for offer fields configured with a token; `null` otherwise.
  - `default_value` object, nullable — Default value applied when a new parent record is created without an explicit value for this field. Shape varies by `value_type` (string for text/url, number for currency/number, option id for single_select, ISO 8601 for date).

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `422` — Unprocessable Content

---

[API](https://skmtc.dev/greenhouse/apis/auth-api.md) · [All operations](https://skmtc.dev/greenhouse/apis/auth-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greenhouse/auth-api/revisions/9517a2e54640/schema)