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

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”.
3

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.
4

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”.
5

Connect

Save the form. Serval then verifies the connection with health checks (see below).
When you later edit this connection, the saved Client Secret appears only as a bullet placeholder with an edit (pencil) or Replace control next to it. Saving any change - even to a different field - without replacing the secret breaks the connection. Every time you save, click the edit or Replace control on the Client Secret and paste the full secret again, and never save with a blank Client ID or Client Secret.

​
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

On the integration settings page, the saved Client Secret shows as an obfuscated value with a pencil (edit) icon; in the reconnect dialog, it shows as a masked value with a Replace button. Whenever you save any change to this connection - even one that only touches another field - click that control and paste the complete Client Secret as part of the same save. Saving without doing so, or saving with a blank or cleared field, breaks authentication. If the connection stops working after an edit, re-enter the full Client ID and full Client Secret and save again.
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. Remember that any save also requires re-entering the full Client Secret (see the first gotcha above), so replace the secret as part of the same 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.