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)
- Whitelist Greenhouse’s server IPs (if required) - see Greenhouse Server IP Addresses for the latest list
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.
Generate Harvest API Key
To generate a Harvest API key, the user with the appropriate developer permission should click the Configure icon 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.
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.
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 Recruiting account [POST/PATCH/DELETE/PUT]) also require an on-behalf-of header that contains a valid Greenhouse Recruiting user ID.
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 > Users > select the user), where you can find the user ID in the URL:
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:
curl -X GET \
-H 'Authorization: Basic ********************' \
"name": "Integration User",