Greenhouse Recruiting's Harvest API allows organizations to build integrations that programmatically read or modify data such as candidates, jobs, and offers. The API includes endpoints for retrieving data (GET), as well as endpoints that support write actions (POST, PUT, PATCH, DELETE).
Harvest API is available in two formats:
- Harvest v1/v2: Uses API keys for authentication
- Harvest v3: Uses OAuth 2.0 client credentials (client ID and client secret)
To connect to any version of the Harvest API, Site Admins must create API credentials, assign endpoint permissions, and optionally restrict access by IP address.
Create Harvest API credentials
To get started, click the Configure icon on your navigation bar and select Dev Center on the left.
Click API Credential Management.
Click Create new API credentials.
In the dialog box that appears, select the Harvest or Harvest v3 (OAuth) for your API type. Choose a partner, if applicable, and a description to identify the integration.
Depending on whether or not you're using Harvest (v1/v2) or Harvest v3, you'll click either Manage permissions or View and store credentials to proceed.
Copy your Harvest API credentials to a secure location. You'll need your API key to authenticate Harvest API requests.
Click I have stored the client credentials or I have store the API key, then assign the appropriate endpoint permissions to your new key.
Set permissions and restrict access by IP
After selecting Manage permissions page, assign access to the data your integration needs.
We recommend assigning only the endpoints or scopes your integration actually needs. Work with your developers or integration partner to determine the appropriate level of access. Click here to learn more about how to manage API key permissions.
The available options in Manage permissions/scopes section vary depending on the type of API credential and your organization’s access, but the steps to assign permissions are the same. Expand the available sections to view and select endpoints or scopes.
To add an extra layer of security, check Restrict access to specific IP addresses and enter trusted IPs or CIDR ranges (for example, 139.186.1.10 or 203.0.113.0/24). Only requests from these IPs will be allowed.
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": []
}
]