Create custom field

Human-readable label for the new field. Must be unique among active fields of the same field_type.

Data type and editor for the field. Determines which payload shape parent resources must use when supplying a value (e.g. currency expects {value, unit}, user expects a Greenhouse user id, single_select/multi_select expect option ids or names). Set at creation only — value_type cannot be changed once the field exists.

Resource the field attaches to (candidate, job, offer, opening, application, user_attribute, etc.). Determines which sibling create endpoint shape applies — see the field-type-specific variants of this request.

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

If true, mints an email merge token that can be used to inject this field's value into candidate emails.

Helper text shown beneath the field label in the UI. Plain text only.

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

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

Human-readable label shown to recruiters and hiring managers (e.g. Cost Center, Start Date). Unique among active fields of the same field_type.

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

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

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.

Job and opening fields only. If true, edits to this field's value route through the job's approval workflow before taking effect.

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.

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.

Id of the Greenhouse user who last edited the field definition, or null if no edit has been recorded.

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.

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

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

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.

Helper text shown beneath the field label in the UI. Plain text, no markup.

Application fields only. Restricts which applications the field appears on: all_applications, candidate_applications (applicants), or prospect_applications. null for non-application fields.

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.

Job fields only. If true, the field is included on the job-approval form so approvers see its value when reviewing the job.

Job fields only. If true, the field's value flows onto the offer-approval form for jobs that route offers through approvals.

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