Harvest API can be used to build integrations that programmatically create or update candidate, job, and organization information.
Harvest API is designed to export candidate, job, and organization information from Greenhouse Recruiting via GET endpoints. However, Harvest also includes powerful POST, PUT, PATCH, and DELETE endpoints that allow you to transform information inside Greenhouse Recruiting.
To connect to Harvest API, you'll need an active Harvest API key with the correct endpoint permissions, a valid Greenhouse Recruiting user ID for the header of your requests, and if necessary, allowlisted access to Greenhouse's server IPs.
Create a Harvest API key
To create a Harvest API key, click the Configure icon 
on your navigation bar and select Dev Center on the left.
Click API Credential Management.
Click Create New API Key, and select Harvest for the API Type.
Click Manage Permissions.
Copy your Harvest API key to a secure location. You'll need your API key to authenticate Harvest API requests.
Click I have stored the API key, then assign the appropriate endpoint permissions to your new key.
Since users with Harvest API keys can access all data in the selected endpoints, we recommend working with your development team or integration partner to determine which endpoints they require access to. Each Harvest API key should only be permitted access to the required endpoints.
Click here to learn more about how to manage API key permissions.
Check any or all endpoint permissions as needed.
When finished, click Save.
Your API key is now ready to use for requests!
Locate or create a user ID for the API connection
Harvest API requests require validation via an on-behalf-of header that includes the value of an active Greenhouse Recruiting user ID who has permission to view the requested data.
Example: If you want to manipulate offer data with Harvest API, you'll need an on-behalf-of header that includes the user ID of a Greenhouse Recruiting user who has permission to see and manage offers.
You can either use an existing Greenhouse Recruiting user ID, or you can create a new integration system user (ISU) specifically for your API requests.
Use an existing Greenhouse Recruiting user ID
To use an existing Greenhouse Recruiting user ID, click the Configure icon on your navigation bar, then click Users on the left.
Select the user from your user list.
The resulting URL in your browser will display the Greenhouse Recruiting user ID.
Example: In the example below, Kelly's Greenhouse Recruiting user ID is 1234567890.
Note: You cannot view your own user profile in Greenhouse Recruiting.
Create an ISU
You can create a user specifically for API requests, called an integration system user (ISU). To create an ISU, click the Configure icon on your navigation bar, then click Users on the left.
Click + New Users and create your new user with the appropriate permissions. Learn more about creating and using ISUs here.
Allowlist Greenhouse server IP addresses
Depending on your organization's security practices, you may need to allowlist Greenhouse server IP addresses in order to make Harvest requests. Learn more about allowlisting server access here.
Make Harvest API requests
When you're ready, you can make Harvest API requests using your API development tool.
- Authenticate your request using your Harvest API key.
- Validate your request using the Greenhouse Recruiting user ID in the on-behalf-of header.
- Query the endpoint with the method you prefer.
Example: You can make a GET: List users request via Harvest to retrieve a list of your organization's users.
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@jmail.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": []
}
]