Sign in

v1

latestOpenAPI 3.1.02026-07-261770816.7 KB
Custom Fields

List custom fields

Custom fields are the org-defined dictionary of structured data your organization layers onto core resources — jobs, offers, openings, candidates, applications, and users. Each row defines one field: its field_type selects the parent resource it attaches to, and its value_type selects the data type and editor (text, number, currency, single/multi-select, date, user, attachment, etc.). Replaces the V1 path-scoped endpoints /v1/custom_fields/{field_type} — filter by field_type as a query parameter instead. For select-type fields, options live on the sibling resource /v3/custom_field_options; office/department visibility lives on /v3/custom_field_offices and /v3/custom_field_departments.

get/v3/custom_fields

Query parameters

cursorstring

Cursor link for pagination from previous page response header. Do not use any other parameters when using this.

per_pageinteger

Number of results per page

idsinteger[]

Comma separated list

gtestring date-time
ltestring date-time
gtstring date-time
ltstring date-time
gtestring date-time
ltestring date-time
gtstring date-time
ltstring date-time
fieldsstring[]

Comma separated list of fields to return

field_type'job' | 'opening' | 'standard' | 'offer' | 'compensation_frequency' | 'candidate' | 'referral_question' | 'application' | 'rejection_question' | 'form' | 'agency_question' | 'user_attribute'

Filter by the resource the field attaches to (e.g. job, offer, candidate, application, opening, user_attribute). Replaces the V1 path segment /v1/custom_fields/{field_type}.

activeboolean

Filter by archival status. Defaults to returning both active and archived; set true for live fields only, false for archived only.

namestring

Filter to fields whose human-readable name exactly matches this value (case-insensitive).

name_keystring

Filter to the field with this name_key (the stable lowercase identifier used when setting values on parent resources). Prefer this over name for integrations — name_key is stable across rename.

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