You can use Harvest API to programmatically add Greenhouse Recruiting users and manage their names, emails, or employment statuses to achieve parity with an outside system like an HRIS. This way you can add, deactivate, and update users at scale.
Manage users
Get a list of users
To sync users with an outside system, use the Harvest API endpoint GET: List users to retrieve all existing users in your organization's Greenhouse Recruiting environment.
curl -X GET \Example response:
'https://harvest.greenhouse.io/v1/users/' -H 'Authorization: Basic *******' \
{
"id": 123456,
"name": "Jasmine Teal",
"first_name": "Jasmine",
"last_name": "Teal",
"primary_email_address": "j.teal@ymail.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"
}
This list can be filtered for specific users with the emails or employee_ID query parameters.
Add new Greenhouse Recruiting users
Use the Harvest API endpoint POST: Add users to add a new user to your Greenhouse Recruiting instance.
Note: First name, last name, and email address are required with the POST: Add users endpoint. We recommend including an employee ID as well for downstream integrations.
Example request:
curl -X POST 'https://harvest.greenhouse.io/v1/users'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic *********\
-H ‘{
"first_name": "Erin",
"last_name": "Smith",
"email": "e.smith@ymail.com",
"send_email_invite": true,
"employee_id": "ABC12345"
}'
Update a user
Use the Harvest API endpoint PATCH: Edit user to update a user's first name, last name, or employee ID. The user element in the request should contain either employee_id or email to ensure the appropriate person is updated.
Example request:
curl -X PATCH 'https://harvest.greenhouse.io/v2/users/'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic ***********\”
-H ‘{
"user": {
"email": "a.tile@ymail.com"
},
"payload": {
"first_name": "Alyson",
"last_name": "Tile",
"employee_id": "ABC12345"
} ‘
Add user email address
If your organization builds an integration that updates employee email addresses based on an outside HRIS, use the Harvest API endpoint POST: Add email address to user to add a new email address to the user.
Example request:
curl -X POST 'https://harvest.greenhouse.io/v1/users/123/email_addresses'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic **********\"
-H ‘{
"email": "j.merson@ymail.com",
"send_verification": true
}'
Note: You can only add a new email address, and not remove or replace an existing email address with Harvest API. Any email address added to a user profile must be verified before it can be used to send emails from Greenhouse Recruiting.
Add user custom fields
To add, update or remove custom user fields on a user account, use the Harvest API endpoint GET: List custom fields to retrieve your organization's custom fields. You can use the query parameter field_type to only retrieve user_attribute fields for a complete list of custom user fields.
Next, use the Harvest API endpoint PATCH: Edit user to add or edit a user's custom user fields with the custom_fields parameter.
Example request:
curl -X GET \ 'https://harvest.greenhouse.io/v1/custom_fields/user_attribute' -H 'Authorization: Basic *******' \
Example response:
[
{
"id": 37070065002,
"name": "IC",
"active": true,
"field_type": "user_attribute",
"priority": 0,
"value_type": "yes_no",
"private": false,
"required": true,
"require_approval": false,
"trigger_new_version": false,
"name_key": "ic",
"description": null,
"expose_in_job_board_api": false,
"api_only": false,
"offices": [],
"departments": [],
"template_token_string": null,
"use_for_job_approvals": false,
"use_for_offer_approvals": false,
"custom_field_options": []
}
]
Example request:
curl -X PATCH \ 'https://harvest.greenhouse.io/v1/custom_fields/user_attribute'
-H 'Authorization: Basic *******' \
-H "On-Behalf-Of: {greenhouse user ID}"
{
"user": {
"email": "e.clifton@ymail.com"
},
"payload": {
"custom_fields": [
{
"id": 37070065002,
"value": "yes"
}
]
}
}
Example response:
{
"success": true,
"message": "User updated",
"user": {
"id": 4654450202
}
}
Deactivate a user
Use the Harvest API endpoint PATCH: Deactivate user to deactivate a Greenhouse Recruiting user account based on a change in employment status in your HRIS.
Example request:
curl -X PATCH 'https://harvest.greenhouse.io/v2/users/disable'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic ***********\”
-H ‘{
"user": {"email": "test@example.com"}
}