How can we help you?

Create/Update Job Through Harvest API

Permissions_and_Product_Tier.png

This article outlines the API requests needed in order to create a new job in Greenhouse Recruiting and import all job information from a third-party system through the Greenhouse Harvest API. 

Note: This article assumes that you have established API Connectivity.

 

Integration Development in Greenhouse Sandbox

Be aware that Greenhouse Recruiting sandbox is not a copy of production. Settings and data cannot be copied over or moved between a Greenhouse Recruiting sandbox and a production instance. The Greenhouse Recruiting sandbox is a secondary empty production instance that can be used for testing integrations, or alternative workflows or settings. Therefore:

  • Greenhouse object IDs (e.g. Job ID, User ID, Custom FIeld ID, etc...) will be different between sandbox and production.
  • The Harvest API key for sandbox will be different than for production.

 

Create New Greenhouse Recruiting Job (POST: Create Job)

The POST request can be used only to initially create the job and add the following default field values:

  • Number of Openings
  • Job Name
  • Department
  • Office
  • Requisition/Opening IDs

You will also need to make a subsequent PATCH: Update Job request to add custom job field values (see: Add custom Job Field Values and Update Existing Jobs).

Only the Greenhouse Recruiting template job ID, number of openings, and job name are required. The template job will be used to populate workflows and objects that cannot be imported via the API (e.g. Scorecards, Interview Plan, Hiring Team, etc...), as Greenhouse Recruiting typically is the source of truth for these items.

Note: We strongly recommend including an Office and/or Department value in the initial POST: Create Job request because the Office(s) and Department a job is assigned to can have many dependent workflows in Greenhouse. Please see the Office and Department Dependent Workflows help guide for more information. We recommend reviewing these dependencies with your recruiting team to see if any will be impacted by your integration.

Below are the additional resources typically required to create the POST: Create Job request:

  • GET: List Jobs: to retrieve the job ID values needed to fill the “template_job_id”
  • GET: List Offices:to retrieve the Greenhouse office ID values or external values stored in Greenhouse Recruiting
  • GET: List Departments: to retrieve the Greenhouse department ID values or external values stored in Greenhouse Recruiting
curl -X POST \
https://harvest.greenhouse.io/v1/jobs \
-H 'Authorization: Basic *******' \
-H 'Content-Type: application/json' \
-H 'on-behalf-of: 123456 \
-d '{
"template_job_id": 1023578,
"number_of_openings": 2,
"job_post_name": "API Test Job - External Name",
"job_name": "API Test Job",
"external_department_id": “GEN”,
"office_ids": [
61348
],
"requisition_id": "ABC",
"opening_ids": [
"ABC-1",
"ABC-2"
]
}'

 

Add Custom Job Field Values and Update Existing Jobs (PATCH: Update Job)

This can be used to update both default and custom job field values on existing jobs, or to add custom field job values to a new job. To make this PATCH request to update custom job field values, you must:

1. GET: List Jobs to pull the Greenhouse job ID for the job you need to update. The below example retrieves the job using the requisition_id “ABC-123”:

curl -X GET \
'https://harvest.greenhouse.io/v1/jobs?requisition_id=ABC-123' \
-H 'Authorization: Basic *******’ \
 

2. GET: List Custom Fields to retrieve all custom job field name keys and available option values for single and multi-select fields

Note: Any single or multi-select field values must match an available field option name or ID in Greenhouse exactly for the PATCH to be successful.

curl -X GET \
https://harvest.greenhouse.io/v1/custom_fields/job \
-H 'Authorization: Basic *******' \

[
{
"id": 152956,
"name": "Short Textbox Test",
"active": true,
"field_type": "job",
"priority": 11,
"value_type": "short_text",
"private": true,
"required": false,
"require_approval": true,
"trigger_new_version": false,
"name_key": "short_textbox",
"custom_field_options": []
},
{
"id": 284617,
"name": "Cost Center",
"active": true,
"field_type": "job",
"priority": 14,
"value_type": "single_select",
"private": false,
"required": true,
"require_approval": true,
"trigger_new_version": false,
"name_key": "cost_center",
"custom_field_options": [
{
"id": 12302153,
"name": "option 1",
"priority": 0
},
{
"id": 12302154,
"name": "option 2",
"priority": 1
},
{
"id": 12302155,
"name": "option 3",
"priority": 2
},
{
"id": 12302156,
"name": "option 4",
"priority": 3
},
{
"id": 12302157,
"name": "option 5",
"priority": 4
}
]
},...
}
]

Once you have retrieved all the custom field name_keys and custom_field_options (where applicable), you can use this request to PATCH an existing job’s custom field values. Below is an example including each available custom field type, for reference. The multi-select and single select fields use text matching to write/update values:

curl -X PATCH \
https://harvest.greenhouse.io/v1/jobs/1019899 \
-H 'Authorization: Basic *******' \
-H 'Content-Type: application/json' \
-H 'on-behalf-of: 123456 \
-d '{
"name": "Updated Job Name",
"department_id":53771,
"external_office_ids": "APAC-1",
"custom_fields":[
{
"name_key":"short_textbox",
"value":"This is a short text field for comments."
},
{
"name_key":"long_textbox",
"value":"This is a long text field for comments exceeding 255 characters."
},
{
"name_key": "cost_center",
"value": "option 4"
},
{
"name_key": "custom_multi_select_field",
"value":
[
"Multi select 1",
"Multi select 2"
]
},
{
"name_key":"recruiter",
"value": 793196
},
{
"name_key": "salary_range",
"min_value": 75000,
"max_value": 95000,
"unit": "USD"
},
{
"name_key": "currency_field",
"value": 87500,
"unit": "USD"
},
{
"name_key": "number_range",
"min_value": 0,
"max_value": 10
},
{
"name_key":"level",
"value":"Mid"
},
{
"name_key": "travel_required_",
"value": "no"
},
{
"name_key": "expiration_date",
"value": "01/01/2020"
},
{
"name_key":"url_example",
"value": "https://testingexample.com"
}
]
}'
 

 

Additional Data

Add a Job Post Description (PATCH: Update Job Post)

Each Greenhouse Recruiting job can have one or more job posts that can be made live on your careers page. The job must already have a placeholder job post created in order to use this endpoint.

  1. Retrieve the job post ID via GET: List Job Posts for Job
  2. Make the PATCH: Update Job Post request:
curl -X PATCH \
https://harvest.greenhouse.io/v1/job_posts/1611527 \
-H 'Authorization: Basic *******' \
-H 'Content-Type: application/json' \
-H 'on-behalf-of: 123456 \
-d '{
"status": "live",
"title": "Ice Cream Vendor",
"location": "New York, NY",
"content": "This is where the job post description should go."
}'

 

Add a Hiring Team to the Job

Click here for information on how to add a Hiring Team to a Job via the API.

 

Add a Job Opening (POST: Create New Openings)

This endpoint can be used to add a new opening to an existing job.

curl -X POST \
https://harvest.greenhouse.io/v1/jobs/1019899/openings \
-H 'Authorization: Basic *******' \
-H 'Content-Type: application/json' \
-H 'on-behalf-of: 123456’ \
-d '{
"opening_id": "ABC-3"
}
}'

 

Edit a Job Opening (PATCH: Edit Openings)

This endpoint can be used to edit an existing opening on a job. You can close an opening via the API, but you cannot re-open a closed opening via the API.

Note: You need to first GET: List Job Openings for the job and use the Greenhouse opening ID that is returned in the response. You can only PATCH open openings, and you are limited to either updating the opening ID or closing the opening (you can not do both at once). The example below demonstrates how you would close opening ID 2460180. Close_reason_id is an optional field, and you can pull the available close reasons via GET: List Close Reasons.

curl -X PATCH \
https://harvest.greenhouse.io/v1/jobs/1019899/openings/2460180 \
-H 'Authorization: Basic *******' \
-H 'Content-Type: application/json' \
-H 'on-behalf-of: 123456’ \
-d '{
"status": "closed",
"close_reason_id": 18137
}'

 

Custom Field Options on Job Fields 

Custom field options can be added and maintained through the API on single select or multi-select custom job fields. You can find more information about this in the following Help Center article: Custom Options Sync Overview.