Harvest API v1 and v2 will be deprecated and unavailable after August 31, 2026. Please make sure that your existing custom integrations use the latest version of Harvest (v3) by this date and any new integrations are developed with the latest version of Harvest API.
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 v3: Uses OAuth 2.0 client credentials (client ID and client secret)
- Harvest v1/v2: Uses API keys for authentication
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": []
}
]View API usage
The usage tab in API Credentials gives technical administrators visibility into how Harvest v3 credentials are being used. Use it to monitor request volume, track error rates by status code, and see which credentials are most active — helping you catch integration issues and understand your usage over time.
To view your API usage, follow the same steps for creating credentials. Click the Configure icon on your navigation bar and select Dev Center on the left. Choose API Credential Management.
From here, make sure you're in the the Harvest v3 (OAuth) tab (you will be brought here by default), then click the usage tab.
Here's you'll see a set of reports that can be controlled by a filter by month.
Filter by month
Use the month filter dropdown near the top of the page to select the time period you want to view. The page defaults to the current month. The timestamp in the upper-right corner shows when the data was last refreshed.
Total requests
This displays the total number of Harvest v3 API calls made during the selected month, along with the overall success rate (the percentage of requests that returned a 2xx response).
Requests by status code
This bar chart shows your daily request volume for the month, with each bar broken down by HTTP response status code. The chart includes the following status codes: 200, 201, 202, 203, 204, 400, 401, 403, 404, 409, 415, 422, 429, and 500.
Hover over any bar to see the request count for each status code on that day.
Use this chart to identify spikes in error responses. A sudden increase in 4xx codes, for example, may indicate an authentication problem or a misconfigured integration hitting endpoints it shouldn't be accessing.
Active credentials
This table lists each Harvest v3 credential that made API calls during the selected month.
For each credential, the table shows:
- Description — The name assigned to the credential
- Client ID — A masked identifier for the credential
- Requests — The total number of API calls made by that credential for the month
- Success rate — The percentage of that credential's requests that returned a 2xx response
For credentials with notable error rates, click Status code details to see a breakdown of that credential's responses by status code.
Use this table to identify which integrations are most active and to flag any unexpected activity that could indicate a compromised or misconfigured key.