Developers using Greenhouse Recruiting's Harvest API to import jobs from an external system may also want to add a hiring team (hiring managers, recruiters, coordinators, or sourcers) to the job. This article describes the process for adding a hiring team to a job using Harvest API.
If all recruiters in your Greenhouse Recruiting instance are Site Admins or already have future Job Admin permissions to all new jobs in their assigned offices or departments, you will only need to retrieve the recruiter's Greenhouse Recruiting user ID (Step 1) and then assign them to the new job's Hiring Team (Step 4).
If all recruiters in your Greenhouse Recruiting instance do not have future Job Admin permissions, you'll need to assign their Job Admin access to each new job first, and then assign their role on the Hiring Team. In this case, you 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, check out our Permissions documentation.
For more information about Harvest API, check out our Developers Resources.
Note: The "on-behalf-of" user in the API request header should have Site Admin permissions to avoid permissions errors.
Step 1 – GET: List users
Use GET: List users 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 *******' \
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
Use GET: List User Roles to retrieve the Job Admin user role ID that you wish to assign the user.
Example
Request
curl -X GET \
https://harvest.greenhouse.io/v1/user_roles \
-H 'Authorization: Basic *******' \
Response
[
{
"id": 02480,
"type": "job_admin",
"name": "Standard"
},
{
"id": 98765,
"type": "interviewer",
"name": "Interviewer"
}
]
Step 3 – PUT: Add job permission
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.
Use the user ID (retrieved in Step 1) and the user role ID (retrieved 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 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, whereas adding the job permission to a user who doesn’t yet have access to the job will return a 201 status.
Step 4 – POST: Add hiring team members
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.
In the example below, the request 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
}
]
}’