How to apply approval flows with the Harvest API

Permissions: Basic and above, who can manage all organization's API Credentials

Product tier: Available to all subscription tiers

Developers who are using the Harvest API to import jobs from an external system and also want to apply custom Job Approval or Offer Approval chains to the job typically use default approvers to streamline the approval flow.

Screen_Shot_2021-08-17_at_4.36.55_PM.png

However, if default Approvals can’t be used because the Approvers don’t consistently depend upon Office and/or Department, developers can follow the steps below to pass the approval flow through the Harvest API. 

See the following sections for more information:

Permissions:

If the users responsible for approvals meet the following criteria, your approval flow can be created using the email address or employee ID for the Greenhouse user:

  • Users who will grant approval are Site Admins and have permissions to grant jobs and approve jobs/offers
  • Users who will grant approvals will be a Job Admin on all future jobs in the relevant office sand departments

See step 4 for more information on this setup.

However, If the users responsible for approvals don't already have the required permissions, you must assign their Job Admin access to each new job, and then create the approval flow.

In this case, the integration should follow all of the steps below to ensure that users have the necessary level of access before adding them to any approval chain.

For more information on Greenhouse user permissions, please see our Permissions documentation.

API request steps

Step 1

Use GET: List User using the email address or Employee ID parameter to identify the particular user that you would like the integration to assign as an approver.

The API response will include the user's ID in the "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"
}

Step 2

Use GET: List User Roles to retrieve the Job Admin user role ID that you wish to assign the user.

The API response will include the Job Admin user role ID that you will assign to the Greenhouse user that will be assigned as an approver. For simplicity's sake, we recommend using one Job Admin level for this particular integration.

Note: the Job Admin level must have the appropriate permissions for approvals (listed below).

  • Job approver permission: Can view and edit private job fields and approve/request approval on jobs.” 
  • Offer approver permission: Can view and edit offers and approve/request approval on offers.

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"
  }
]

Step 3

Assign Job Admin permissions to the user on the job in question before creating the approval flow.  Use the user ID (retrieved in Step 1), the user_role_ID (retrieved in Step 2), and add the appropriate Job Admin permission for the job to the Greenhouse user using the PUT: Add Job Permission request.

Note: In addition to the API key, this write request requires an on-behalf-of user ID header with the appropriate permissions. See the  Establish API Connectivity article for more information on making write requests to the API. 

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: 1049756' \
-d '{
"job_id": "11111",
"user_role_id": "02480"
}’

Note: If the user 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; adding the job permission to a user who doesn’t yet have access to the job will return a 201 status.   

Step 4

Once the user has the appropriate permissions on the job, you can create an approval flow including them as one of the approvers via the PUT: Create or replace an approval flow endpoint. The example below would add a two-step offer approval: the first example contains two required approvals, while the second step contains just one required approval.

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": "offer_candidate",
   "offer_id": null,
   "sequential": true,
   "approver_groups": [
       {
           "approvals_required": 2,
           "approvers": [
               { "user_id": 123456},
               { "email": "first.last@company.com"}
           ]
       },
       {
           "approvals_required": 1,
           "approvers": [
               { "employee_id": "ABC-123" }
           ]
       }
   ]
}'