You can create a custom integration to use Greenhouse Recruiting's job and offer approval flows with an outside system, so that jobs or offers created in Greenhouse Recruiting follow the approvals or approval flows that you outline in your HRIS.
While there are many ways to integrate Greenhouse Recruiting with an outside system for approvals, we've collected a few common use cases for your organization to consider.
Job approvals
We commonly see organizations use Harvest API to create a custom integration that updates job approval flows in Greenhouse Recruiting based on information from an outside system such as an HRIS. Jobs in Greenhouse Recruiting can be set to follow one-stage or two-stage approval flows, and they are applied to jobs at the time the job is created.
Job approval using Harvest API
You can use Harvest API to create an integration that updates job approval flows based on information from an outside system.
Use the endpoint GET: List User with the email address or employee ID parameter to identify the particular user that you would like to assign as an approver. The API response will include the user's ID in id.
Example request:
curl -X GET \
'https://harvest.greenhouse.io/v1/users?email=test@example.com' \
-H 'Authorization: Basic *******' \
Example response:
{
"id": 123456,
"name": "Greenhouse Test",
"first_name": "Greenhouse",
"last_name": "Test",
"primary_email_address": "test@example.com",
"updated_at": "2019-04-01T17:32:41.665Z",
"created_at": "2017-09-13T17:43:56.968Z",
"disabled": false,
"site_admin": false,
"emails": [
"test@example.com"
],
"employee_id": "abc123"
}
Next, use the endpoint GET: List User Roles to retrieve the Job Admin user role ID that you wish to assign the user. This reflects the Job Admin level in Greenhouse Recruiting. For simplicity's sake, we recommend using one Job Admin level for this particular integration.
Note: The Job Admin level must have the appropriate permission to approve jobs:
- Can view and edit private job fields and approve / request approval on jobs
Example request:
curl -X GET \
https://harvest.greenhouse.io/v1/user_roles \
-H 'Authorization: Basic *******' \
Example response:
[
{
"id": 02480,
"type": "job_admin",
"name": "Standard"
},
{
"id": 98765,
"type": "interviewer",
"name": "Interviewer"
}
]
Next, assign Job Admin permissions to the person on the job before creating the approval flow.
Using the user ID and the user_role_ID, query the endpoint PUT: Add Job Permission to edit their permission on the job.
Note: In addition to authenticating with a Harvest API key, any write request requires validation via an on-behalf-of user ID header. Check out Harvest API overview for more information.
Example request:
curl -X PUT \
https://harvest.greenhouse.io/v1/users/123456/permissions/jobs \
-H 'Authorization: Basic *******' \
-H 'Content-Type: application/json' \
-H 'on-behalf-of: 0123456789' \
-d '{
"job_id": "11111",
"user_role_id": "02480"
}’
Note: If a person already has Site Admin permissions (which by default gives them access to all jobs), this request will have no effect and will return a 204 status.
Once the person has the appropriate permissions on the job, you can create an approval flow including them as one of the approvers via the endpoint PUT: Create or replace an approval flow endpoint.
Example request:
curl -X POST \
https://harvest.greenhouse.io/v1/jobs/11111/approval_flows \
-H 'Authorization: Basic *******' \
-H 'Content-Type: application/json' \
-H 'on-behalf-of: 1049756' \
-d '{
"approval_type": "open_job",
"sequential": true,
"approver_groups": [
{
"approvals_required": 1,
"approvers": [
{ "user_id": 123456},
{ "email": "first.last@company.com"}
]
}
]
}'
Offer approvals
Offer approvals apply to candidate offers at the time they are created. Most organizations create department or office-specific offer approvals.
Since approvals are applied at the time of offer creation, if syncing offer approvals or approval flows from an outside system, we recommend using offer placeholders to ensure that no offer is automatically approved in error. There are a couple of ways to accomplish this depending on the method your organization prefers.
Offer creation and approval in an outside system
With this method, offer creations and approvals are managed in an outside system such as an HRIS, then a candidate is marked as hired in Greenhouse Recruiting.
First, create an offer in Greenhouse Recruiting to serve as a placeholder, with just the start date filled out. Your team can then leverage Greenhouse web hooks to send information to your HRIS to create the offer, gain offer approval, and mark the candidate as hired in the outside system. You can then use our APIs so that Greenhouse Recruiting can sync updates from your HRIS for end-to-end reporting parity.
Example
Use the offer created or offer updated webhook. The payload will include offer details including custom fields such as establishment ID, job code, or other unique identifiers for your integration to leverage.
Next, use the Harvest API endpoint GET: Retrieve job with the job id parameter to retrieve additional information that may not be included in the webhook payload, such as requisition information.
With the info collated, create the offer in your HRIS or outside system and apply approval flows via job code, requisition ID, position ID, or other unique identifiers.
Once the offer is approved, use the endpoint PATCH: Update offer to update the offer in Greenhouse Recruiting to match the information from your outside system.
Finally, use the endpoint POST: Hire application to hire the candidate after they accept the offer and before new employee BP is completed.
Offer creation and approval in Greenhouse Recruiting
With this method, you can manage offer creation and approval in Greenhouse Recruiting, but dynamically update information from an outside system such as an HRIS.
Dynamic offers
You can create offers in Greenhouse Recruiting that respond to information from an outside system.
Example
First, create the offer in Greenhouse Recruiting with only the start date filled out and any unique identifiers that will be used by your integration.
Next, use the offer created or offer updated web hooks to send offer information to your HRIS.
Use middleware or a listener service to ping your HRIS via API for offer information via establishment id, job code, requisition id, or other unique identifiers.
Finally, use the Harvest endpoint PATCH: Update offer to update the offer details based on the information retrieved from your HRIS.
Dynamic approvals
You can create offers in Greenhouse Recruiting that respond to approval flows from an outside system.
Example
First, create the entire offer in Greenhouse Recruiting.
Next, use the offer created or offer updated web hooks to send offer information to your HRIS.
Use middleware or a listener service to ping your HRIS via API for offer approval groups in the outside system. You can query via establishment id, job code, requisition id, or other unique identifiers.
Once you've identified the approval group, use the Harvest endpoint PUT: Add a job permission to assign permission on the job to the approvers.
Finally, use the endpoint PUT: Replace approver in a group to replace the approval flow on the offer in Greenhouse Recruiting.