Sync offices and departments from an external system

Permissions: Site Admin

Product tier: Available for all subscription tiers

It's possible to add new offices and departments using Greenhouse Recruiting's Harvest API. However, offices and departments are organization-level fields that can be tied to permissions, approval chains, jobs, custom fields, template jobs, and more. Due to these dependencies, there are some limitations on how offices and departments can be updated through Harvest API.

For more information on these dependencies, check out: Office and department-dependent workflows.

You can add new offices and departments as a parent or child office or department with the following API endpoints:

Note: If you're importing these values from an HCM or other third-party system, we recommend including an External ID value.

If you're adding a child office or department, you'll need to specify the Greenhouse Recruiting parent office or department ID in the "parent_id" field. You can use the external_id querystring parameter on GET: List offices and GET: List departments to retrieve the Greenhouse Recruiting office or department ID that's required for your POST requests.

Example:

curl -X POST \
 https://harvest.greenhouse.io/v1/departments \
 -H 'Authorization: Basic ***********************' \
 -H 'Content-Type: application/json' \
 -H 'On-Behalf-Of: 642569' \
 -d '{
 "name": "NewChilddepartment",
 "parent_id": 45819,
 "external_id": "ABC123"
}'

Update existing office names, locations, or external IDs, and existing department names or external IDs via the following endpoints:

You'll need to use the Greenhouse Recruiting office or department ID in the HTTP request in order to specify the appropriate office / department to update.

Example: The following call would update the office with the Greenhouse Recruiting ID 63683.

curl -X PATCH \
 https://harvest.greenhouse.io/v1/offices/63683 \
 -H 'Authorization: Basic ***********************' \
 -H 'Content-Type: application/json' \
 -H 'on-behalf-of: 642569' \
 -d '{
 "name": "Updated office Name",
 "location": "New York, NY",
 "external_id": "ABC123456"
}'

Limitations

The following actions are not possible using Harvest API:

Removing offices or departments – We do not recommend this in general for the purpose of preserving historical job data.
Updating office or department hierarchy – For example, you can't make a subordinate office a parent office by using Harvest API.

In this article

Sync offices and departments from an external system

Limitations