> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/it-service-management/greenhouse-ats-oauth.md).

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

{% hint style="info" %}
This integration connects to **Greenhouse Recruiting** (the ATS). It is a separate product from **Greenhouse Onboarding**, which has its own [Greenhouse Onboarding](/integrations/hris/greenhouse-onboarding.md) integration for new hire and employee data. Connecting one does not affect the other.
{% endhint %}

***

#### 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

{% hint style="info" %}
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.
{% endhint %}

***

#### 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](#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.

***

#### 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                 |

{% hint style="info" %}
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.
{% endhint %}

***

#### Greenhouse workflow blocks

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

<details>

<summary>List Jobs</summary>

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.

</details>

<details>

<summary>Create Application</summary>

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

</details>

{% hint style="info" %}
The **Create Application** block writes to Greenhouse. Treat it like any other write action in a workflow and review the inputs before publishing.
{% endhint %}

**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

<details>

<summary>Blocks fail with a permissions error</summary>

**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

</details>

<details>

<summary>The connection stopped working after a period of inactivity</summary>

**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

</details>

<details>

<summary>List Jobs returns no results</summary>

**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

</details>

<details>

<summary>A referral was created but is not credited to the referrer</summary>

**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

</details>

***

#### Data & Privacy

<details>

<summary>Key privacy principles</summary>

For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).

* 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

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.harmony.io/integrations/it-service-management/greenhouse-ats-oauth.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.