---
title: "List custom field options"
method: GET
path: "/v3/custom_field_options"
tags: ["Custom Field Options"]
---

# List custom field options

`GET /v3/custom_field_options`

## Request

- Base URL: `https://harvest.greenhouse.io`
- URL: `https://harvest.greenhouse.io/v3/custom_field_options`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://auth.greenhouse.io/authorize`
    - Client credentials
    - Token URL: `https://auth.greenhouse.io/token` scopes: `harvest:custom_field_options:list`
  - HTTP bearer

Custom field options are the selectable values on a `single_select` or `multi_select` custom field — each row belongs to exactly one custom field via `custom_field_id`. Filter to a specific dictionary with `custom_field_ids` (preferred when the id is known) or `custom_field_key` (e.g. `school_name`, `degree`, `discipline`, `cost_center`). The V1 endpoints `/v1/schools`, `/v1/degrees`, and `/v1/disciplines` are all served here in V3 — pass the matching `custom_field_key`. Archived options remain in results by default; pass `active=true` to restrict to currently selectable options.

## Query parameters

- `cursor` string
- `per_page` integer
- `ids` integer[]
- `created_at` object
  - `gte` string, date-time
  - `lte` string, date-time
  - `gt` string, date-time
  - `lt` string, date-time
- `updated_at` object
  - `gte` string, date-time
  - `lte` string, date-time
  - `gt` string, date-time
  - `lt` string, date-time
- `custom_field_ids` integer[]
- `fields` string[]
- `active` boolean
- `custom_field_key` string

## Response `200`

Successful

- object[]
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `custom_field_id` integer: Id of the parent custom field this option belongs to. Only fields with `value_type` of `single_select` or `multi_select` carry options.
  - `name` string: Display label shown to recruiters and hiring managers in dropdowns (e.g. `Engineering`, `Bachelor's`, `Stanford University`). Unique among active options on the same parent custom field.
  - `external_id` string, nullable: Caller-supplied identifier from the partner's source system (typically an HRIS row id or legacy ATS id). Persisted verbatim as the column `offsite_hris_id` and not interpreted by Greenhouse.
  - `sort_order` integer: Display position within the parent custom field's dropdown. Lower values render first; ties fall back to insertion order. Alias of `priority` in V1/V2.
  - `active` boolean: `true` while the option is selectable. Set to `false` after deletion — historical selections on candidates, jobs, and offers are preserved so the value still resolves on existing records.

---

[API](https://skmtc.dev/greenhouse/apis/harvest-api.md) - [All operations](https://skmtc.dev/greenhouse/apis/harvest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/greenhouse/apis/harvest-api/revisions/822822e3f771?raw)