v1

latestOpenAPI 3.1.02026-07-261770816.7 KB

Openings

Update opening

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.

patch/v3/openings/{id}

Path parameters

idinteger required

Request body

job_idinteger

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_idstring

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_idinteger

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_onstring date

Target start date for the hire that will fill this opening, in ISO 8601 (YYYY-MM-DD).

Response

Successful

idinteger

created_atstring date-time

updated_atstring date-time

job_idinteger

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_atstring 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_atstring 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_orderinteger

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_idstring 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_idinteger 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_idinteger 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_onstring 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.

openboolean

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_fieldsobject nullable