Skip to main content

About Greenhouse

Greenhouse is an applicant tracking system (ATS) for managing recruiting pipelines: candidates, applications, interview stages, and jobs. Serval connects to the Greenhouse Harvest API (v3) and calls it on demand from workflows - for example, to create a candidate or advance an application to a new stage. This integration covers the Harvest v3 surface only; Job Board, webhooks, and Greenhouse Onboarding are not included. Authentication: OAuth 2.0 client credentials - a Client ID and Client Secret from a Greenhouse Harvest API integration credential. Serval mints a short-lived token for each request automatically. Data sync: On demand only. Serval reads or writes Greenhouse data when a workflow step runs. There is no background sync, no entity ingestion, and no webhooks.

What the Greenhouse integration enables

The integration exposes a growing slice of the Greenhouse Harvest API v3; additional surfaces are planned as future phases.

Get your credentials

Serval needs a Harvest V3 (OAuth) API credential from Greenhouse. When you create one, Greenhouse automatically provisions an Integration Service User (ISU) for it - by default, every Serval call runs as that user. See the Greenhouse Harvest API v3 reference for background.
1

Log in to Greenhouse

Sign in as a user with permission to create and manage API credentials.
2

Open API Credential Management

Go to Configure > Dev Center > API Credential Management.
3

Create the credential

Create a new API credential, choose Harvest V3 (OAuth) as the credential type, and enter a descriptive name such as “Serval Integration”.
4

Copy the Client ID and Client Secret

Save the credential and copy both values.
5

Check the credential's access

In Greenhouse, make sure the credential’s Integration Service User can access the data your workflows will touch - candidates, applications, jobs, and users at minimum. You can adjust this in Greenhouse at any time.
6

Optional: note a Site Admin user ID

If your workflows need elevated access for list endpoints, open a Site Admin user’s profile in Greenhouse and copy the numeric user ID from the profile URL. You can enter it as the Authorizing User ID in Serval.
Store the Client Secret securely - anyone who has it can request Harvest tokens for your Greenhouse account.
Serval’s token requests contain no OAuth scopes and Serval has no permission settings of its own. What the integration can read and write is governed entirely by the access Greenhouse grants the credential and its Integration Service User (or the Authorizing User, if you set one).

Connect in Serval

1

Open the Greenhouse connect form

In Serval, add a new Greenhouse integration.
2

Choose the API region

Automatic keeps your saved region when reconnecting and uses Default for new connections. Select Default (harvest.greenhouse.io), EU (harvest.eu.greenhouse.io), or US (harvest.us.greenhouse.io) to choose a specific region. The dashboard address, such as s101.recruiting.eu.greenhouse.io, is not an API address.
3

Enter the Client ID (required)

The OAuth Client ID from your Greenhouse Harvest API integration credential. It also serves as the connection’s unique identifier. Leaving it blank shows “This field is required”.
4

Enter the Client Secret (required)

The OAuth Client Secret for the same credential, entered as a password field. After you connect, Serval never shows it in full again - it displays obfuscated as bullets plus the last 4 characters.
5

Optionally enter an Authorizing User ID

A numeric Greenhouse user ID. Use a Site Admin’s ID if list endpoints need elevated access; leave blank to run as the Integration Service User. Only digits are accepted - anything else is rejected with an error that includes “Authorizing User ID must be a numeric Greenhouse user ID”.
6

Connect

Save the form. Serval then verifies the connection with health checks (see below).
You can change the API region without re-entering the Client ID or Client Secret. Serval preserves saved credentials when their fields are unchanged. Token requests use https://auth.greenhouse.io/token for every API region.

Verifying the connection

After you connect, Serval runs three health checks against your Greenhouse account:
  • Test Greenhouse Harvest Connection - confirms Serval can authenticate to the Harvest API by listing users. Success: “Successfully authenticated with the Greenhouse Harvest API.” Failure: “Unable to connect to Greenhouse. Verify that the Client ID and Client Secret are correct and that the Integration Service User has Harvest API permissions.”
  • List Open Greenhouse Jobs - verifies the integration can list open jobs by fetching a small sample. Success: “Successfully listed open jobs from Greenhouse (sample size: [number]).” Failure: “Unable to list open jobs from Greenhouse. Verify that the Integration Service User has access to job data.”
  • List Greenhouse Candidates - verifies the integration can list candidates by fetching a small sample. Success: “Successfully listed candidates from Greenhouse (sample size: [number]).” Failure: “Unable to list candidates from Greenhouse. Verify that the Integration Service User has access to candidate data.”
If “Test Greenhouse Harvest Connection” passes but the jobs or candidates checks fail, your credentials are valid but the Integration Service User cannot see that data. Either grant the Integration Service User access to that data in Greenhouse, or set the Authorizing User ID to a Site Admin’s numeric Greenhouse user ID so requests run with that user’s access.

Gotchas and troubleshooting

Edit the connection and select its API region. Leave the saved Client ID and Client Secret unchanged to keep them. To rotate the secret, use the pencil icon or Replace control and enter the new secret before saving. Run the health checks after changing regions or credentials.
By default, calls run as the Integration Service User that Greenhouse auto-provisions for the credential, and that user may lack access to job or candidate data. Set the Authorizing User ID to a Site Admin’s numeric Greenhouse user ID so Serval makes requests as that user instead.
The field accepts only digits - leading and trailing whitespace is trimmed, and any other character is rejected with an error that includes “Authorizing User ID must be a numeric Greenhouse user ID”. Use the numeric ID from the Greenhouse user’s profile URL, not an email address or name.
To go back to running as the Integration Service User, clear the Authorizing User ID field in the connection settings and save.
Serval does not send or manage OAuth scopes, and there are no permission toggles on the Serval side. Access is governed entirely by what the credential’s Integration Service User (or the Authorizing User, if set) is allowed to do in Greenhouse. If a workflow hits permission errors, adjust the credential’s access in Greenhouse’s API Credential Management, or point the connection at a different Authorizing User ID.
The integration covers the Harvest API v3 surface only. Legacy Harvest v1 calls (including the v1 On-Behalf-Of behavior), the Job Board API, webhooks, and Greenhouse Onboarding are not supported and are planned as future phases.

Need help? Contact support@serval.com for assistance with your Greenhouse integration.