---
title: "Create opening"
method: POST
path: "/v3/openings"
tags: ["Openings"]
---

# Create opening

`POST /v3/openings`

Add a new headcount slot to an existing job. `job_id` is required; `opening_id` is an optional partner-supplied external identifier (e.g. an HRIS or ATS position id) and `custom_fields` set values on the organization's opening custom fields. Greenhouse enforces an internal limit of 100 open openings per job — requests that would exceed it are rejected. To create a batch of openings alongside a new job, use `POST /v3/jobs` with `number_of_openings` instead.

## Request body

- object
  - `job_id` integer, required — Id of the parent job (requisition) to add this opening to. Required. Greenhouse enforces an internal limit of 100 open openings per job; requests that would exceed it are rejected.
  - `opening_id` string — Partner-supplied external identifier for the new opening (e.g. an HRIS or ATS position id). Free-form string, not required to be unique across the organization. Distinct from the Greenhouse `id`.
  - `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`).
    - 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 `201`

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)