---
title: "Update job"
method: PATCH
path: "/v3/jobs/{id}"
tags: ["Jobs"]
---

# Update job

`PATCH /v3/jobs/{id}`

## Request

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

Patch an existing job's editable fields. Only the keys included in the request body are modified; omitted keys are left untouched. `office_ids` / `external_office_ids` and `custom_fields` replace their existing collections wholesale — send the full desired list, not a delta. Department and office can be set either by Greenhouse id or by partner `external_id`; the two forms are mutually exclusive. To open, close, or re-open a job, modify its openings through `/v3/openings` — the job's `status` and `opened_at`/`closed_at` follow automatically.

## Path parameters

- `id` integer, required

## Request body

- object
  - `name` string: Internal job title shown to the hiring team in Greenhouse.
  - `notes` string: Internal HTML notes about the job. Replaces the existing value when supplied.
  - `anywhere` boolean, nullable: If `true`, the job is marked as remote-anywhere and `office_ids` is cleared. Mutually exclusive with supplying `office_ids` or `external_office_ids`.
  - `requisition_id` string, nullable: Partner-supplied external identifier for the requisition. Pass `null` to clear the value.
  - `team_and_responsibilities` string: Internal description of the team and the role's responsibilities, shown to the hiring team in the Greenhouse UI.
  - `how_to_sell_this_job` string: Internal selling-points note used by recruiters when pitching the role, shown to the hiring team in the Greenhouse UI.
  - `office_ids` integer[], nullable: Replace the job's office assignments with these office ids. Send the full desired list, not a delta. Mutually exclusive with `external_office_ids` and with `anywhere: true`.
  - `external_office_ids` string[], nullable: Replace the job's office assignments by partner-supplied office `external_id` values. Each entry is resolved to a Greenhouse `office_id` in the caller's organization; unknown values are rejected. Mutually exclusive with `office_ids`.
  - `department_id` integer, nullable: Set the job's department by Greenhouse id. Pass `null` to clear. Mutually exclusive with `external_department_id`.
  - `external_department_id` string, nullable: Set the job's department by partner-supplied department `external_id`. Resolved to a Greenhouse `department_id` in the caller's organization; unknown values are rejected. Mutually exclusive with `department_id`.
  - `custom_fields` union[]: Values to set on this job's job custom fields. Replaces the existing collection wholesale — send the full desired list, not a delta. Each entry identifies the field by `custom_field_id` or `name_key` and supplies a `value` matching the field's `value_type`.
    - 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
            - number
            - string
          - 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
            - number
            - string
          - 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
  - `ignore_custom_field_requirements` boolean: If `true`, a `null` value sent via `custom_fields` for a required field clears it instead of failing the request. Restricted to integration service-account credentials; other callers are rejected with a 422.
  - `ignore_approver_permission_check` boolean: If `true`, skips the check that a user set as a job or offer approver via `custom_fields` has permission to view/edit this job. Lets an integration assign an approver without first broadening that user's Greenhouse permissions. Restricted to integration service-account credentials; other callers are rejected with a 422.

## Response `200`

Successful

- object
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `name` string: Internal job title shown to the hiring team in Greenhouse (e.g. `Senior Backend Engineer`). Distinct from the external-facing title on each `job_post`.
  - `requisition_id` string, nullable: Partner-supplied external identifier for the requisition (e.g. an HRIS or ATS code). Free-form string, not unique across the organization, and `null` when no external id has been set.
  - `notes` string, nullable: Internal HTML notes about the job, surfaced to the hiring team in the Greenhouse UI. Not exposed on public job posts.
  - `confidential` boolean: If `true`, the job is restricted to users explicitly granted access on the Hiring Team. The legacy Confidential Jobs feature has been sunset — this flag cannot be set on new jobs and is preserved for jobs that already had it enabled.
  - `status` 'open' | 'draft' | 'closed': Lifecycle status of the job. `draft` while it is being scaffolded, `open` once it has at least one open opening, and `closed` after every opening is closed. A job moves to `closed` automatically when its last open opening is closed via `PATCH /v3/openings/{id}`.
  - `opened_at` string, date-time, nullable: Timestamp the job first transitioned to `open`, in ISO 8601. `null` while the job is still in `draft`.
  - `closed_at` string, date-time, nullable: Timestamp the job most recently transitioned to `closed`, in ISO 8601. `null` for jobs that are still `open` or `draft`.
  - `is_template` boolean, nullable: If `true`, this job is a template used as the source for new jobs rather than a real requisition. Templates do not accept applications; reference them via `template_job_id` on `POST /v3/jobs`.
  - `copied_from_id` integer, nullable: Id of the job (typically a template) this job was copied from on creation. `null` when the job was not created from another job.
  - `department_id` integer, nullable: Id of the department this job is assigned to. `null` when no department is set.
  - `external_department_id` string, nullable: `external_id` of the department this job is assigned to, for partners that reconcile jobs against an HRIS by external id. Mirrors the `external_department_id` accepted on create and update. `null` when no department is set or the department has no external id.
  - `office_ids` integer[], nullable: Ids of the offices this job is assigned to. A job can span multiple offices; empty array or `null` when no offices are set.
  - `external_office_ids` string[]: `external_id`s of the offices this job is assigned to, for partners that reconcile jobs against an HRIS by external id. Mirrors the `external_office_ids` accepted on create and update. Offices with no external id set are omitted, so this can be shorter than `office_ids`.
  - `custom_fields` object, nullable: Job custom field values keyed by each field's `name_key`. Only includes fields that apply to this job's offices and departments, by the same rules the Job Info page uses. A field restricted to offices or departments (see `GET /v3/custom_field_offices` and `GET /v3/custom_field_departments`) is left out unless the job is in one of them or in a child of one. A field restricted on both needs a match on each. A job with no offices or departments includes every field. `PATCH /v3/jobs/{id}` returns a 422 for a non-null value on a field left out here. A field that applies but has no value is returned with `value: null`.

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