How to: Sync users with an outside system using Greenhouse Harvest API

Permissions: Basic or above, who can manage ALL organization's API credentials

Product tier: Available for all subscription tiers

You may need to leverage Greenhouse Harvest APIs to programmatically add Greenhouse Recruiting users and manage their names, emails, or employment statuses via an outside system like an HRIS.

In this article, we'll cover how to sync users with an outside HRIS using Greenhouse APIs. With Greenhouse's Harvest API you can add new users, deactivate existing users, and update user details.

Review the sections below for more information:

Sync Greenhouse Recruiting users

Syncing users is typically considered an additional integration, and is not required to import jobs, but it may help expedite your organization's management of the Greenhouse Recruiting user database.

Get a list of users

You can use the Greenhouse Harvest API endpoint GET: List Users to retrieve all existing users in your organization's Greenhouse Recruiting instance. This list can be filtered for specific users by using the emails or employee_ID parameters.

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

Add new Greenhouse Recruiting users

You can use the Greenhouse 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 also advise including an employee ID for any downstream integrations.

Example request:

curl -X POST 'https://harvest.greenhouse.io/v1/users'

-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic *********\
-H ‘{
"first_name": "Bob",
"last_name": "Smith",
"email": "bob@email.org",
"send_email_invite": true,
"employee_id": "ABC12345"
}'

Update an existing Greenhouse Recruiting user

You can use the Greenhouse Harvest API endpoint PATCH: Edit User to update a user's first name, last name, email address, or employee ID. The user element in the request should contain either employee_id or email to ensure the appropriate user is updated.

Example request:

curl -X PATCH 'https://harvest.greenhouse.io/v2/users/'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic ***********\”
-H ‘{
"user": {
"email": "test@example.com"
},
"payload": {
"first_name": "John",
"last_name": "Smith",
"employee_id": "ABC12345"
} ‘

Deactivate an existing Greenhouse Recruiting user

You can use the Greenhouse Harvest API endpoint PATCH Disable 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"}
}

Add an email address to an existing Greenhouse Recruiting user

If your organization would like to build an integration that updates employee's email address based on an outside HRIS, you can use the Greenhouse Harvest API endpoint  POST: Add email address to user to add a new email address to a user.

Note: You cannot remove or replace an existing email address via Harvest API. Additionally, any email address must be verified before it can be used to send emails from Greenhouse Recruiting.

Example request:

curl -X POST 'https://harvest.greenhouse.io/v1/users/123456/email_addresses'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic **********\"
-H ‘{
"email": "test@example.com",
"send_verification": true
}'

Additional resources

If you would like more information about managing Greenhouse Recruiting user accounts and permissions via Harvest API, refer to the following resources: