--- title: "Update opening" method: PATCH path: "/v3/openings/{id}" tags: ["Openings"] --- # Update opening `PATCH /v3/openings/{id}` Patch an existing opening's editable fields, or change its status. Only the keys included in the request body are modified; omitted keys are left unchanged. Pass `status: "closed"` to close an open opening. Include `close_reason_id` when closing if your organization requires one. Closing the last open opening on a job automatically closes the job. Pass `status: "open"` to reopen a closed opening that has not been filled; reopening a filled opening returns 422. `custom_fields` replaces the opening's custom-field values wholesale, so send the full desired list, not a delta. ## Path parameters - `id` integer, required ## Request body - object - `job_id` integer — Id of the job (requisition) this opening belongs to. Provided to disambiguate the opening; reassigning an opening to a different job is not supported. - `opening_id` string — Partner-supplied external identifier for the opening (e.g. an HRIS or ATS position id). Free-form string, not required to be unique across the organization. - `close_reason_id` integer — ID of the `close_reason` to record when closing the opening, for example Hire - New Headcount, On Hold, or Requisition Cancelled. Resolve via `GET /v3/close_reasons`. On an open opening, supplying `close_reason_id` without also setting status to closed returns 422; on an already-closed opening, `close_reason_id` can be updated on its own. - `status` 'open' | 'closed' — Transition the opening's lifecycle. Pass `closed` to close an open opening (optionally with `close_reason_id`); pass `open` to reopen a closed opening that has not been filled. - `target_start_on` string, date — Target start date for the hire that will fill this opening, in ISO 8601 (`YYYY-MM-DD`). - `custom_fields` union[] — Values to set on this opening's opening custom fields. Each entry identifies the field by `custom_field_id` or `name_key` and supplies a `value` whose shape matches the field's `value_type` (see `GET /v3/custom_fields?field_type=opening`). Replaces the existing values wholesale — send the full desired list, not a delta. - union - object - `name_key` string, required — Required if custom_field_id is not provided. Exactly one of name_key or custom_field_id must be specified. - `custom_field_id` integer — Required if name_key is not provided. Exactly one of name_key or custom_field_id must be specified. - `value` union - string - string - string - string - string - boolean - number — User ID - union - string[] - number[] - number - object - `amount` number, required - `currency_code` string, required - object - `min_amount` number, required - `max_amount` number, required - `currency_code` string, required - object - `min_value` number, required - `max_value` number, required - object - `name_key` string — Required if custom_field_id is not provided. Exactly one of name_key or custom_field_id must be specified. - `custom_field_id` integer, required — Required if name_key is not provided. Exactly one of name_key or custom_field_id must be specified. - `value` union - string - string - string - string - string - boolean - number — User ID - union - string[] - number[] - number - object - `amount` number, required - `currency_code` string, required - object - `min_amount` number, required - `max_amount` number, required - `currency_code` string, required - object - `min_value` number, required - `max_value` number, required ## Response `200` Successful - object - `id` integer - `created_at` string, date-time - `updated_at` string, date-time - `job_id` integer — Id of the parent job (requisition) this opening belongs to. Each opening is a single headcount slot under the job; the job carries the role's configuration and is the source of truth for things like the interview plan and hiring team. - `opened_at` string, date-time, nullable — Timestamp the opening first transitioned to `open` (i.e. became available to be filled), in ISO 8601. `null` while the opening's job is still in `draft`. - `closed_at` string, date-time, nullable — Timestamp the opening was closed, in ISO 8601. `null` while the opening is still `open`. Closing the last open opening on a job automatically closes the job itself. - `sort_order` integer — Position of the opening within the job's openings list, used to preserve the order in which openings were created or arranged in Greenhouse. - `opening_id` string, nullable — Partner-supplied external identifier for the opening (e.g. an HRIS or ATS position id). Free-form string, not required to be unique across the organization, and `null` when no external id has been set. Distinct from the Greenhouse `id`. - `application_id` integer, nullable — Id of the application that filled this opening when it was closed as a hire. `null` for openings that are still `open` or that were closed without a hire. - `close_reason_id` integer, nullable — Id of the `close_reason` recorded when the opening was closed (e.g. `Hire - New Headcount`, `On Hold`, `Requisition Cancelled`). `null` when the opening is still `open` or when it was closed without a close reason. Resolve via `GET /v3/close_reasons`. - `target_start_on` string, date, nullable — Target start date for the hire that will fill this opening, in ISO 8601 (`YYYY-MM-DD`). `null` when no target start date has been set. - `open` boolean — Convenience flag — `true` while the opening is still available to be filled, `false` once it has been closed (filled or otherwise). Equivalent to `closed_at` being `null`. - `custom_fields` object, nullable ## Other responses - `401` — Unauthorized - `403` — Forbidden - `422` — Unprocessable Content --- [API](https://skmtc.dev/greenhouse/apis/auth-api.md) · [All operations](https://skmtc.dev/greenhouse/apis/auth-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greenhouse/auth-api/revisions/9517a2e54640/schema)