Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Greenhouse ATS (OAuth)

Connect Greenhouse Recruiting to Harmony for job discovery and referral automation

The Greenhouse (OAuth) integration connects Harmony to your Greenhouse Applicant Tracking System over Greenhouse's Harvest V3 API. Once connected, your Harmony workflows and agents can list open jobs and create candidates and applications in Greenhouse - including employee referrals with a CV attached - without leaving Harmony.

This integration replaces the API key based Greenhouse ATS integration.

This integration connects to Greenhouse Recruiting (the ATS). It is a separate product from Greenhouse Onboarding, which has its own Greenhouse Onboarding integration for new hire and employee data. Connecting one does not affect the other.

What the Greenhouse (OAuth) integration enables

Capability
Description

Job Discovery

List open, non-confidential positions from Greenhouse, with department and location resolved

Referral Automation

Create a candidate and their application in Greenhouse directly from a Harmony workflow

CV Attachments

Attach a candidate's resume to the application as part of the same workflow step

Referral Attribution

Credit the referring employee and the organization's referral source on the new application

OAuth Authorization

Authorize once as a Site Admin - no API keys to generate, store, or rotate

Prerequisites

  1. Greenhouse Recruiting with Harvest V3 API access

  2. Greenhouse Site Admin access - Harvest V3 list endpoints require a Site Admin grant, so the person who authorizes the connection must be a Site Admin in Greenhouse

  3. A Harmony account with admin privileges

The Greenhouse (OAuth) integration is being rolled out gradually. If you do not see the card in your Integrations page, contact Harmony support to have it enabled for your workspace.

Connect Greenhouse to Harmony

Step 1: Navigate to Integrations

  1. Log into your Harmony dashboard

  2. Navigate to Settings > Integrations

  3. Find Greenhouse (OAuth) under ATS

Step 2: Authorize Greenhouse

  1. Initiate the connection

    1. Click the Greenhouse (OAuth) integration card

    2. Click Connect

    A Greenhouse authorization window will open.

  2. Authorize in Greenhouse

    Sign in with your Greenhouse Site Admin account if prompted.

    1. Confirm the Greenhouse organization you are authorizing

    2. Review the permissions Harmony is requesting (see Permissions Explained below)

    3. Click Authorize to approve the connection

    4. The window closes automatically and you are returned to Harmony

Once authorized, the integration is active and the Greenhouse workflow blocks become available in the workflow builder.

Migrating from the API key integration

If your workspace already has the API key based Greenhouse ATS integration connected, Harmony will warn you when you connect this one - running both pulls the same recruiting data twice.

The recommended order is:

  1. Connect Greenhouse (OAuth) and confirm the authorization succeeds

  2. Update any workflows that use the Greenhouse blocks to point at the new Greenhouse ATS (OAuth) blocks

  3. Disconnect the old Greenhouse ATS integration

Both integrations can be connected at the same time during the migration, but the old one should be disconnected once the move is complete.

Permissions Explained

Harmony requests the following Harvest V3 scopes during authorization:

Scope
Purpose

harvest:jobs:list

List your open positions for the List Jobs block

harvest:departments:list

Resolve a job's department name - jobs in Harvest V3 carry only department ids

harvest:offices:list

Resolve a job's office names into a location - jobs carry only office ids

harvest:candidates:list

Look up an existing candidate by email before creating a new one, to avoid duplicates

harvest:applications:list

Check whether the candidate has already applied to the job before creating a second application

harvest:candidates:create

Create the candidate and their application for the Create Application block

harvest:attachments:create

Attach the candidate's CV to the application

harvest:sources:list

Resolve your organization's referral source so referrals are attributed correctly

harvest:users:list

Resolve the referring employee to their Greenhouse user, to credit the referral

Harvest V3 list endpoints require the authorizing user to be a Greenhouse Site Admin. If the connection was authorized by a non-admin user, Greenhouse rejects these calls and the blocks will fail with a permissions error - reconnecting as a Site Admin resolves it.

Greenhouse workflow blocks

Once connected, two blocks become available under ATS > Greenhouse ATS (OAuth) in the workflow builder.

List Jobs

Returns open, non-confidential positions from Greenhouse. Each job includes its title, department, location, and status. Supports searching by title and paging through large job boards.

Closed and draft jobs, and jobs marked confidential in Greenhouse, are excluded.

Create Application

Creates a candidate in Greenhouse and their application to a specific job in a single step - the typical use is an employee referral submitted through a Harmony workflow.

Optionally attaches the candidate's CV and credits the referring employee and your organization's referral source.

CV attachments:

  • Supported formats: .pdf, .doc, .docx

  • Maximum file size: 4 MB

The Create Application block writes to Greenhouse. Treat it like any other write action in a workflow and review the inputs before publishing.

Partial success warnings

The application itself is always created if the candidate and job are valid. Some optional parts can fail on their own, and the block reports them as warnings rather than failing the whole step:

Warning
Meaning

cv_upload_failed

The application was created but the CV could not be attached

cv_unsupported_type

The attached file is not a .pdf, .doc, or .docx

cv_too_large

The attached file exceeds the 4 MB limit

referrer_not_found

No Greenhouse user matched the referring employee, so the referral is uncredited

referral_source_not_found

No referral source is configured in Greenhouse, so the source is unset

note_upload_failed

The application was created but the referral note could not be added

Disconnect Greenhouse from Harmony

  1. Log into your Harmony dashboard

  2. Navigate to Settings > Integrations

  3. Find Greenhouse (OAuth) under ATS and click the integration card

  4. Click Disconnect

  5. Confirm the disconnection when prompted

Once disconnected, workflows using the Greenhouse ATS (OAuth) blocks will stop working. You can also revoke Harmony's access from within Greenhouse.

Troubleshooting

Blocks fail with a permissions error

Possible causes:

  • The connection was authorized by a user who is not a Greenhouse Site Admin

  • One or more scopes were not granted during authorization

Solutions:

  1. Disconnect the integration

  2. Reconnect and complete the authorization while signed in as a Greenhouse Site Admin

  3. Grant all requested permissions on the Greenhouse authorization screen

The connection stopped working after a period of inactivity

Possible causes:

  • Greenhouse expires an OAuth grant that has been idle for 24 hours

Solutions:

  1. Disconnect and reconnect the integration to establish a fresh authorization

List Jobs returns no results

Possible causes:

  • All matching jobs are closed, in draft, or marked confidential in Greenhouse

  • The search term does not match any job title - Harvest V3 matches on job title only

Solutions:

  1. Confirm the jobs are open and not confidential in Greenhouse

  2. Broaden or remove the search term

A referral was created but is not credited to the referrer

Possible causes:

  • The referring employee's email does not match a Greenhouse Recruiting user

  • Your Greenhouse account has no referral source configured

Solutions:

  1. Confirm the referring employee exists as a user in Greenhouse with the same email address

  2. Configure a referral source in Greenhouse under your organization's candidate sources

Data & Privacy

Key privacy principles

For information about how Harmony handles your data, see our Privacy Policy.

  • Harmony reads job, department, office, source, and user data from Greenhouse to support workflow execution

  • Harmony writes to Greenhouse only when a workflow explicitly runs the Create Application block

  • Authorization is held as an OAuth grant and can be revoked at any time from Greenhouse or from Harmony settings

PreviousGreenhouse ATS
NextHelp Scout

Last updated

Was this helpful?