Closing a job preserves all the configurations made on the job while restricting users from adding candidates to the job, visiting the job dashboard, or submitting scorecards to the job on Greenhouse Recruiting. Additionally, this action unpublishes the job's job posts from all of your organization's job boards.
There are many reasons you may close a job:
- Making the necessary new headcount or backfill hires
- The job is placed on hold while your organization priorities other roles
- Your organization has implemented a hiring freeze
- The job is temporarily not being filled
Note: All active candidates will remain active on a closed job. We suggest your organization reject these candidates or move them to another job.
The Greenhouse Harvest API allows your team to close jobs in your Greenhouse Recruiting account programmatically.
Create a Harvest API key
In order to close a job in Greenhouse Recruiting via Harvest API, you'll first need to generate an API key with the proper permissions.
Note: To create an API key, you must be a Basic user and above with the additional user-specific permission 'Can manage ALL organization’s API credentials.'
To create a Harvest API key, click the Configure icon on your navigation bar, and select Dev Center on the left.
From the Dev Center page, click API Credential Management.
From the API Credential Management page, click Create New API Key.
In the Create New Credential dialog box, make the following selections:
- API Type: Harvest
- Partner: Leave blank
- Description: Harvest API
When finished, click Manage Permissions to generate the Harvest API key.
In the subsequent dialog box, click Copy to save your API key to your clipboard. Store the API key in a secure location to share with your developers. Click I have stored the API Key once you have copied and saved the key.
Note: You cannot access the full Harvest API key again after clicking I have stored the API Key. If you lose your API key and need to access it later, you must create a new API key and then revoke access to the original key.
On the subsequent page, assign the following permissions:
- GET: List Jobs
- GET: List Openings For a Job
- PATCH: Edit job openings
When you've finished selecting the appropriate endpoints, click Save at the bottom of the page.
You have successfully created a Harvest API key! Provide the key to your internal development team as appropriate.
Close a job in Greenhouse Recruiting via Harvest API
Now that your API key is generated, your development team can use it to close a job in Greenhouse Recruiting using Harvest API.
There are a few API endpoints that are useful to programmatically close jobs in Greenhouse Recruiting.
1. GET: List Jobs
Use the GET: List Jobs Harvest API endpoint to retrieve the Greenhouse job_ID value on the job you wish to close.
- You may filter the GET: List Jobs endpoint by a specific job using the
requisition_idparameter.
Example: A JSON request on the GET: List Jobs endpoint would look like:
curl -X GET \
'https://harvest.greenhouse.io/v1/jobs?requisition_id=abc123\
-H 'Authorization: Basic *******' \
A successful JSON response on the GET: List Jobs endpoint would look like:
{
"id": 6404,
"name": "Archaeologist",
"requisition_id": "abc123",
"notes": "<p>We need a qualified professional for this role.</p>",
"confidential": false,
"status": "closed",
"created_at": "2013-12-10T14:42:58Z",
"opened_at": "2013-12-11T14:42:58Z",
"closed_at": "2013-12-12T14:42:58Z",
"updated_at": "2013-12-12T14:42:58Z",
"is_template": false,
"copied_from_id": 2345,
"departments": [
{
"id": 25907,
"name": "Second-Level department",
"parent_id": 25908,
"child_ids": [14510],
"external_id": "12345"
}
]
2. GET List Job Openings
Use the GET: List Job Openings Harvest API endpoint on the job_ID from the previous step to retrieve all of the job openings for the job that you would like to close.
Note: If all openings on a job in Greenhouse Recruiting are closed, the job’s status will also be closed.
Example: A JSON request on the GET: List Job Openings endpoint would look like:
curl -X GET \
'https://harvest.greenhouse.io/v1/jobs/6404/openings
-H 'Authorization: Basic *******' \
A successful JSON response on the GET: List Job Openings endpoint would look like:
[
{
"id": 4530863002,
"opening_id": null,
"status": "closed",
"opened_at": "2019-05-07T16:25:25.661Z",
"closed_at": "2019-05-14T17:47:35.107Z",
"application_id": null,
"close_reason": {
"id": 4012092002,
"name": "On Hold"
},
"custom_fields": {
"test_field_name": null
},
"keyed_custom_fields": {
"test_field_name": null
}
},
{
"id": 4542441002,
"opening_id": null,
"status": "open",
"opened_at": "2019-05-14T17:49:25.590Z",
"closed_at": null,
"application_id": null,
"custom_fields": {
"test_field_name": null
},
"keyed_custom_fields": {
"test_field_name": null
}
}
]
3. PATCH: Edit Openings
Use the PATCH: Edit Openings Harvest API endpoint to close all open openings in Greenhouse Recruiting on the job you wish to close.
- After the last opening on a job is closed, Greenhouse will automatically close the job.
- The PATCH: Edit Openings endpoint requires both the Greenhouse
job_IDand the Greenhouseopening_ID.
Note: When closing an opening via Harvest API, it is possible to include a close_reason_id to categorize the reason for the close (see GET: List Close Reasons).
Example: A JSON request on the PATCH: List Openings endpoint would look like:
curl -X GET \
'https://harvest.greenhouse.io/v1/jobs/6404/openings/4542441002
-H 'Authorization: Basic *******' \
-H 'on-behalf-of: 1049756' \
-d ‘{
"opening_id": "4542441002",
"status": "closed",
"close_reason_id": 1234,
}’
Additional resources
You can access Greenhouse Developer Resources to learn more about Harvest API calls, and the endpoints referenced in this article. Check out general Harvest API considerations in our Developer Resources > Harvest API > Introduction.