Close a job in Greenhouse Recruiting via Harvest API

Permissions: Basic and higher, who can manage ALL organization's API credentials

Product tier: Available to all subscription tiers

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. 

In this article, we will cover:

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 generate an API key, you must be a Basic user or above with the additional user-specific permission Can manage ALL organization’s API credentials.

To generate a Harvest API key, click the Configure icon Configured_Icon.png in the upper-right corner. Navigate to Dev Center on the left panel.

Configure_-_Dev_Center.png

From the Dev Center page, click API Credential Management.

API_Credential_management.png

From the API Credential Management page, click Create New API Key.

Create_new_API_key.png

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.

Manage_Harvest_API_key.png

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.

Store_API_key.png

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_id parameter.

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_ID and the Greenhouse opening_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.

Read more about general Harvest API considerations in our Developer ResourcesHarvest API > Introduction.