How can we help you?

Establish API Connectivity

site_admin_all.png

This article outlines the steps to establish connectivity with the Greenhouse Harvest API. The following items are required if you are building an integration between Greenhouse and third-party systems that will read and write data to Greenhouse via the API:

  • An active Harvest API key with the correct permissions (for read and write requests)
  • A valid user ID in the “on-behalf-of” header (for write requests)
  • Whitelist Greenhouse’s server IPs (if required) - see Greenhouse Server IP Addresses for the latest list

 

Developer Permissions

If you are developing an integration and do not have a Greenhouse account, you will need assistance from a Greenhouse user who has the following developer permission Can manage All organization's API Credentials to complete the steps below. Any Greenhouse user (Site Admin, Job Admin, or Basic) can be assigned a developer permission. Click here for more information.

Screen_Shot_2019-06-17_at_12.27.06_PM.png

 

Generate Harvest API Key

To generate a Harvest API key, the user with the appropriate developer permission should click the Configure icon configure.png in the upper right-hand corner and navigate to Dev Center on the left-hand panel.

From the Dev Center page, click API Credential Management.

3.png

From the API Credential Management page, click Create New API Key to generate the API key. Click here to learn more about how to manage API key permissions.

4.png

 

How do I determine which endpoints to whitelist?

Since users with Harvest API keys can access all the data in specified endpoints, we recommend working with your development team or integration partner to determine which endpoints they require access to. Each key should only be allowed to access the endpoints it absolutely needs.

 

Why is a Greenhouse User ID needed for API requests?

For auditing purposes, write requests, that is, API requests that can modify data in your Greenhouse account (POST/PATCH/DELETE/PUT), also require an “on-behalf-of” header that contains a valid Greenhouse user ID.

This allows Greenhouse to log who made which changes and surface this data for Site Admin users in the Change Log, which can be accessed via Configure configure.png > Change Log.

The ability to successfully complete write requests is dependent on the permissions of the user ID in the on-behalf-of header. For this reason, we recommend creating a dummy “Integration User” with appropriate permissions per the integration requirements (for example: if the integration is intended to create jobs, the Integration User should have the user-specific permission to create new jobs and request job approvals).

We advise against using an employee’s Greenhouse user ID to avoid any confusion when it comes to who is responsible for certain actions.

Once you have determined which user you woud like to use in the “on-behalf-of” header, there are two ways to retrieve the user’s ID.

1. Via the UI, you can navigate to the user's edit page (via Configure configure.png > Users > select the user), where you can find the user ID in the URL:

dsdfg.png

2. Via the API, you can pull a list of all users and their corresponding user IDs by making a request to the List Users endpoint. The Greenhouse user ID will be the number returned in the id field (this should not to be confused with the employee_id field). For example:

Request
curl -X GET \
https://harvest.greenhouse.io/v1/users \
-H 'Authorization: Basic ********************' \

Response
[
{
"id": 1049756,
"name": "Integration User",
"first_name": "Integration",
"last_name": "User",
"primary_email_address": "integrationuser@gmail.com",
"updated_at": "2019-03-28T18:29:46.015Z",
"created_at": "2019-03-26T22:23:46.414Z",
"disabled": false,
"site_admin": true,
"emails": [
"integrationuser@gmail.com"
],
"employee_id": "INTUSER123",
"linked_candidate_ids": []
}
]