How to sync users with an outside system using the API

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

Product tier: Available to all subscription tiers

 

This article is intended for customers that would like to leverage Greenhouse’s APIs to automatically add Greenhouse users and manage their name/email/status with an outside system, like an HRIS.

 

This article will cover the following user actions with the Greenhouse Harvest API:

 

Syncing Users
With Greenhouse’s Harvest API you can add new users, disable existing users, and update user details. Syncing users is typically considered an additional integration, and is not required to import jobs, however it may aid and expedite in your organization's management of a Greenhouse user database.

 

Get a list of users:

 

You can use the GET List Users endpoint to retrieve all existing users in your organization’s Greenhouse instance. This list can be filtered for specific users by using the email address 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"

}



Adding new users

 

You can use POST: Add Users to add a new user to your Greenhouse instance. Note that first name, last name and email address are required. We also advise including the employee ID for any downstream integrations.

 

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"

}’



Updating an existing user

You can use the PATCH: Edit User endpoint to update the user’s First Name, Last Name, email address, or employee id via the API. The user element in the request should contain either ‘employee_id’ or 'email’ to ensure the appropriate user is updated.

 

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"

  } ‘

 

Disabling an existing user 

You can use the PATCH Disable User endpoint to deactivate a Greenhouse user account based on a change in employment status in your HRIS.

 

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




Adding an email address to an existing email address

If your organization would like to build an integration that updates employee’s email address based on an outside system, you can use the POST Add Email Address to User endpoint to add a new email address to a user (note you cannot remove or replace an existing email address via API, and an email address must be verified before it can be used to send emails from Greenhouse)

 

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

}’




If your organization would like more information about managing permissions with the API for Greenhouse user accounts, refer to this support article for further information.