0%

Greenhouse Integration Guide

Step 1: Overview

Connect Ferretly to Greenhouse

Customer instructions for authorizing secure Harvest v3 access on Windows or macOS.

Purpose: This process authorizes Ferretly to retrieve candidate information from your Greenhouse organization. It does not reveal your Ferretly key to Greenhouse OAuth and does not provide Ferretly with your Greenhouse password.

What this connection does

  • Connects your Ferretly organization to your Greenhouse organization.

  • Allows Ferretly to retrieve candidate and prospect profiles, education information, and required organization setup information.

  • Stores encrypted access and refresh tokens within Ferretly's integration service.

  • Lets Ferretly refresh access automatically after the initial authorization.

What this connection does not do

  • It does not enable the Ferretly stage in Greenhouse. Greenhouse must enable that integration separately.

  • It does not start a background check by itself. A recruiter must send the Ferretly background check from the candidate workflow.

  • It does not require access to Azure, Ferretly infrastructure, or Ferretly's OAuth client secret.

Step 2: Before you begin

Gather these items before you generate an authorization link:

You need

Requirement

Ferretly key

Your organization-specific Ferretly External API key, supplied through an approved secure channel.

Greenhouse access

A Greenhouse Site Admin account for the organization you are connecting.

Integration stage

The Ferretly background check integration must already be enabled in your Greenhouse organization.

Local access

Windows PowerShell or macOS Terminal.

Step 3: Windows setup

Use Windows PowerShell. Paste and run each complete code block in order.

Step 1: Enter the Ferretly key securely

PowerShell masks the key while you type or paste it.

$secureApiKey = Read-Host 'Ferretly External API key' -AsSecureString

$apiKey = (
    [System.Net.NetworkCredential]::new('', $secureApiKey).Password
).Trim()

$basic = [Convert]::ToBase64String(
    [Text.Encoding]::UTF8.GetBytes("${apiKey}:")
)

$headers = @{
    Authorization = "Basic $basic"
}

Step 2: Generate the authorization link

$connection = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://ferretly-greenhouse.azurewebsites.net/api/greenhouse/oauth/authorization-url' `
    -Headers $headers

$connection |
    Select-Object authorization_url, expires_at |
    Format-List

The response shows the authorization link and its expiration time.

Step 3: Open Greenhouse and authorize

Start-Process $connection.authorization_url

  1. Sign in with a Greenhouse Site Admin account.

  2. Confirm that the page names Ferretly and shows the expected permissions.

  3. Authorize the connection. Wait for: Greenhouse is connected to Ferretly. You may close this window.

Step 4: Confirm the connection

$status = Invoke-RestMethod `
    -Uri 'https://ferretly-greenhouse.azurewebsites.net/api/greenhouse/oauth/status' `
    -Headers $headers

$status |
    Select-Object connected, status, scopes, last_api_success_at, error_code |
    Format-List

A successful connection shows connected = True, status = connected, the approved scopes, and an empty error_code. last_api_success_at may remain blank until Ferretly first retrieves a candidate.

Step 5: Clear temporary values

Remove-Variable apiKey, basic, headers, connection, status `
    -ErrorAction SilentlyContinue

Step 4: macOS setup

These commands use zsh, the default shell in current macOS versions. Paste and run each complete code block in order.

Step 1: Enter the Ferretly key securely

Terminal does not display the key while it is entered.

read -s "FERRETLY_API_KEY?Ferretly External API key: "
echo

Step 2: Generate the authorization link

RESPONSE=$(curl --silent --show-error --fail \
  --request POST \
  --user "${FERRETLY_API_KEY}:" \
  'https://ferretly-greenhouse.azurewebsites.net/api/greenhouse/oauth/authorization-url')

AUTH_URL=$(printf '%s' "$RESPONSE" | \
  plutil -extract authorization_url raw -o - -)

EXPIRES_AT=$(printf '%s' "$RESPONSE" | \
  plutil -extract expires_at raw -o - -)

printf 'Authorization link expires at: %s\n' "$EXPIRES_AT"

Step 3: Open Greenhouse and authorize

open "$AUTH_URL"

  1. Sign in with a Greenhouse Site Admin account.

  2. Confirm that the page names Ferretly and shows the expected permissions.

  3. Authorize the connection and wait for confirmation that Greenhouse is connected to Ferretly.

Step 4: Confirm the connection

curl --silent --show-error --fail \
  --user "${FERRETLY_API_KEY}:" \
  'https://ferretly-greenhouse.azurewebsites.net/api/greenhouse/oauth/status' | \
  plutil -p -

A successful connection shows connected as true, status as connected, the approved scopes, and an empty error_code. last_api_success_at may be null until the first candidate is retrieved.

Step 5: Clear temporary values

unset FERRETLY_API_KEY RESPONSE AUTH_URL EXPIRES_AT
50%