How can we help you?

Add Hiring Team To Job Through the API

Note: The “on-behalf-of” user in the API request header should have Site Admin permissions to avoid permissions errors

This article is intended for developers who are using the Harvest API to import Jobs from an external system and also want to apply the Hiring Team (e.g. Hiring Manager, Recruiter, etc...) to the job.

435sd.png

If all recruiters in your Greenhouse instance are Site Admins or already have future Job Admin permissions to all new jobs in their assigned Offices and/or Departments, all the integration will need to do is retrieve the recruiter's Greenhouse user ID (Step 1) and then assign them to the new job's Hiring Team (Step 4).

If all recruiters in your Greenhouse instance do not have future Job Admin permissions, you will need the integration to assign their Job Admin access to each new job first, and then assign their role on the Hiring Team. 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 the Hiring Team.

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

 

Step 1

GET List User using the email address or Employee ID parameter to identify the particular user. The API response will include the user's ID in the "id" field.

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

GET List User Roles to retrieve the Job Admin user role ID that you'd like to assign the user.

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 adding them to the Hiring Team. For simplicity's sake, we recommend using one Job Admin level for this particular integration.

Use the user ID (retrieved in Step 1) and the user role ID (retrieve in Step 2) and add the user to a job ID using the PUT Add Job Permission request.

Note: In addition to the API key, this write request also requires an on-behalf-of header (see the  Establish API Connectivity article for more information 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, whereas 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 add them to the Hiring Team via the POST Add Hiring Team Members endpoint (example below would add the user as the “Responsible Recruiter” for future, active, and inactive candidates on job 11111):

Example Request:

curl -X POST \
https://harvest.greenhouse.io/v1/jobs/11111/hiring_team \
-H 'Authorization: Basic *******' \
-H 'Content-Type: application/json' \
-H 'on-behalf-of: 1049756' \
-d '{
"recruiters": [
{
"user_id": 123456,
"responsible_for_future_candidates": true,
"responsible_for_active_candidates": true,
"responsible_for_inactive_candidates": true
}
]
}’