GRgreenhouse
Custom Fields

Update custom field

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.

patch/v3/custom_fields/{id}

Request

  • Base URL
    https://harvest.greenhouse.io
  • URL
    https://harvest.greenhouse.io/v3/custom_fields/{id}
  • Auth
    • OAuth 2
      Authorization code: https://auth.greenhouse.io/authorize
      Client credentials
      Token URL: https://auth.greenhouse.io/token scopes: harvest:custom_fields:update
    • or HTTP bearer

Path parameters

idinteger required

Request body

namestring

New display label for the field. Renaming does not change name_key — integrations keyed off name_key continue working.

descriptionstring

New helper text shown beneath the field label in the UI.

privateboolean

If true, only users granted the matching View Private permission can see this field's values.

template_token_stringstring

Updated merge token usable in offer letter templates.

Response

Successful

idinteger
created_atstring date-time
updated_atstring 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_orderinteger

Display priority within the field group on this field_type. Lower values render first; alias of priority in V1/V2.

namestring

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}.

privateboolean

If true, only users granted the matching View Private permission can see or edit this field's values.

requiredboolean

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_approvalboolean

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_versionboolean

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.

activeboolean 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_idinteger 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_apiboolean

Job fields only. If true, the field's value is exposed on the public Job Board API alongside the job listing.

placeholderstring nullable

Greyed-out hint text shown inside an empty field input in the UI.

name_keystring

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.

descriptionstring 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_onlyboolean 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_approvalsboolean 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_approvalsboolean 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_stringstring nullable

Merge token usable in offer letter templates (e.g. {{CUSTOM_FIELD_NAME}}). Returned for offer fields configured with a token; null otherwise.

default_valueobject 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).

Changes

No recorded changes to this operation across all 1 revision of this API.