How can we help you?

Establish API Connectivity

Permissions_and_Product_Tier.png

This article outlines the steps to establish connectivity with the Greenhouse Harvest API. The following are required if you are building an integration between Greenhouse Recruiting and third-party systems that will read and write data to Greenhouse Recruiting via Harvest 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)
  • Allowlist 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 Recruiting account, you will need assistance from a Greenhouse Recruiting user who has the developer permission Can manage All organization's API Credentials to complete the steps below. Any Greenhouse Recruiting 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.

Dev_Center_-_API_Credential_Management.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.

Create_API_Key.png

 

How do I determine which endpoints to allowlist?

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 Recruiting account [POST/PATCH/DELETE/PUT]) also require an on-behalf-of header that contains a valid Greenhouse Recruiting user ID.

This allows Greenhouse Recruiting 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

Example: If the integration is intended to create jobs, the Integration User should have the user-specific permission Can create new jobs and request job approvals.

We advise against using an active 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 would 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:

mceclip1.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 Recruiting 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": []
}
]