Permissions:

Product tier: Available for all subscription tiers

Harvest API can be used to create integrations or to programmatically 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 API 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 on-behalf-of 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 Configure icon on your navigation bar and select Dev Center on the left.

Screenshot of Configure > Dev Center

Click API Credential Management.

Screenshot of Configure > Dev Center > API Credentials Management

Click Create New API Key, and select Harvest for the API Type.

Screenshot of Create New API key button

Click Manage Permissions.

Screenshot of Manage permissions button

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.

Screenshot of Copy API key button

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.

Screenshot of configure credential permissions

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 Configure icon icon on your navigation bar, then click Users on the left.

Screenshot of Configure > Users button

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.

Screenshot of an example user ID

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 Configure icon icon on your navigation bar, then click Users on the left.

Screenshot of Configure > Users

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.

  1. Authenticate your request using your Harvest API key.
  2. Validate your request using the Greenhouse Recruiting user ID in the on-behalf-of header.
  3. 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@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": []
}
]