---
title: "Update department"
method: PATCH
path: "/v3/departments/{id}"
tags: ["Departments"]
---

# Update department

`PATCH /v3/departments/{id}`

## Request

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

Update an existing department's name, `external_id`, or position in the department tree. Use `parent_id` (or `external_parent_id`) to re-parent the department; both are optional on update and the existing parent is preserved when neither is supplied.

## Path parameters

- `id` integer, required

## Request body

- object
  - `name` string, required: New display name for the department. Required.
  - `parent_id` integer, nullable: Id of an existing department to set as the new parent. Set to `null` to remove the parent. Use `parent_id` when you already have the Greenhouse id; use `external_parent_id` to reference the parent by its external id instead.
  - `external_id` string, nullable: Partner-supplied identifier for the department, typically the matching id from an HRIS or other external system. Set to `null` to clear the existing `external_id`.
  - `external_parent_id` string, nullable: `external_id` of an existing department to set as the new parent. Set to `null` to remove the parent. Useful when you only have external ids on hand; ignored if `parent_id` is also supplied.

## Response `200`

Successful

- object
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `name` string: Display name of the department (e.g. `Engineering`, `Marketing`).
  - `parent_id` integer, nullable: Id of the parent department in the organization's department tree. `null` for top-level departments. References another `/v3/departments` row.
  - `external_id` string, nullable: Partner-supplied identifier for the department, typically the matching id from an HRIS or other external system. Free-form string and `null` when no external id has been set.
  - `external_parent_id` string, nullable: `external_id` of the parent department, for partners that key the department hierarchy by external id rather than Greenhouse id. Mirrors the `external_parent_id` accepted on create and update. `null` for top-level departments and when the parent has no external id set.

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