---
title: "Create custom field option"
method: POST
path: "/v3/custom_field_options"
tags: ["Custom Field Options"]
---

# Create custom field option

`POST /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:create`
  - HTTP bearer

Add a new selectable value to a `single_select` or `multi_select` custom field. The parent field is identified by `custom_field_id` in the request body. If an archived option with the same name already exists on the field, this call reactivates that option under its original id instead of creating a duplicate.

## Request body

- object
  - `name` string, required: Display label for the option. Must be unique among active options on the same custom field. If an archived option on the field already has this name, the create reactivates that option under its original id instead of adding a duplicate.
  - `sort_order` integer, required: Display position within the dropdown. Lower values render first. Greenhouse does not normalize gaps, so partners managing reorderings typically space values (e.g. 10, 20, 30) to leave room for inserts.
  - `custom_field_id` integer, required: Id of the parent custom field. Must be a `single_select` or `multi_select` field in the caller's organization.
  - `external_id` string: Optional caller-supplied identifier from the partner's source system (e.g. an HRIS row id). Stored verbatim and returned on subsequent reads as `external_id`.

## Response `201`

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.

## Other responses

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

---

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