In some cases, your organization may need to initiate job creation in Greenhouse Recruiting and subsequently update the Greenhouse Recruiting job with information that is hosted in an HRIS.
This article outlines the workflow and API requests needed in order to update a job in Greenhouse Recruiting and import certain job information from an external HRIS by utilizing Greenhouse Recruiting's 'job created' webhook and the Greenhouse Harvest API.
Web hook initiated job import workflow
When building a jobs integration between an HRIS and Greenhouse Recruiting, your organization may find that the HRIS is the source of truth for key data associated with particular roles, but doesn’t account for position/requisition creation and/or approval.
In these situations, your team may need to initiate job creation in Greenhouse Recruiting, and subsequently update the Greenhouse Recruiting job with information that is hosted in the HRIS.
In order to accomplish this goal, we recommend utilizing the 'job created' web hook and the Harvest API endpoint PATCH: Update job.
Workflow:
1. Create a job in Greenhouse Recruiting.
2. Enter the job code, job profile, and/or level (whatever serves as the key identifier for the job attributes in the HRIS) on the Greenhouse Recruiting job.
Note: In this article we’ll refer to the job code, job profile, and/or level as the "HRIS Job Code."
3. The integration will receive the 'job created' web hook.
4. The integration will use the HRIS Job Code to retrieve job information from the external system (HRIS/HCM).
5. The integration will then update the Greenhouse Recruiting job with information from the HRIS.
Web hook initiated job import diagram
Technical workflow: Catch the 'job created' web hook
The 'job created' web hook will send a payload of job data, including the HRIS Job Code, as soon as a job is created in Greenhouse Recruiting. This can then be used to gather the job information associated with that HRIS Job Code values in the HRIS.
1. Configure the 'job created' web hook to send to the web hook listener in the integration layer/middleware.
2. Catch the 'job created' web hook in the integration layer.
Example
{
"action": "job_created",
"payload": {
"job": {
"id": 371417,
"name": "Software Engineer",
"requisition_id": null,
"notes": "Looking for the best!",
"confidential": false,
"job_post_id": 2154,
"status": "open",
"created_at": "2016-10-20T18:16:32Z",
"opened_at": "2016-10-20T18:16:32Z",
"closed_at": null,
"custom_fields": {
>"job_code": {
"name": "JobCode",
"type": "single_select",
"value": “R101”
}
}
}
}
}
}
3. After catching the 'job created' web hook, the integration will use the HRIS Job Code value included in the web hook payload to retrieve the appropriate data from the HRIS (e.g. salary range, cost center, and other attributes associated with said Job Code in the HRIS). The integration should also store the Greenhouse Recruiting job ID included in the web hook.
4. Once the HRIS attribute values associated with HRIS Job Code are retrieved, the integration should use the stored Greenhouse Recruiting job ID in an API request to update the Greenhouse job’s corresponding custom field values.
Update or add default/custom job field values to existing jobs
Using the web hook initiated job import integration workflow, you may need to add or update default and custom job field values on existing jobs.
To make a PATCH request to update custom job field values:
1. Use the Harvest API endpoint 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.
Example
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
}
]
},...
}
]
2. Once you have retrieved all custom job field name keys and available option values for single and multi-select fields, use the PATCH: Update job request to PATCH an existing job's custom field values.
Example
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"
}
]
}'
3. If you would like to incorporate updates to HRIS Job Code attributes so that any updates in the HRIS push over to the relevant Greenhouse Recruiting jobs, you may want to incorporate a scheduled cadence to check for updates, for example at the end of each day.
A.) Use the Harvest API endpoint GET List Jobs for all open or draft jobs in Greenhouse Recruiting, and store the Greenhouse Recruiting job ID and HRIS Job Code value.
B.) Cycle through each HRIS Job Code to retrieve the latest corresponding HRIS attribute values.
C.) For each HRIS Job Code, cycle through each Greenhouse Recruiting job with its respective HRIS Job Code value and use the Harvest API endpoint PATCH Update Job to overwrite the values that exist in Greenhouse Recruiting with the latest information from the HRIS.