Greenhouse Harvest API Integration

Overview

Query and analyze recruitment data from the Greenhouse Harvest API v3 conversationally. Handle requests for candidate counts, application statuses, interview schedules, pipeline conversions, and other talent acquisition metrics.

Setup

Install Dependencies

First, install the required Python packages:

pip install -r requirements.txt

Or install manually:

pip install requests

Authentication Setup

The Greenhouse Harvest API v3 uses OAuth authentication with client credentials. Set the following environment variables:

export GREENHOUSE_CLIENT_ID="your-client-id"
export GREENHOUSE_CLIENT_SECRET="your-client-secret"
export GREENHOUSE_USER_ID="your-user-id"  # Optional - defaults to service account

Getting OAuth credentials:

1. Go to Greenhouse: Configure → Dev Center → API Credential Management
2. Create a new credential and select "Harvest V3 (OAuth)"
3. Copy the Client ID and Client Secret
4. Optionally specify a User ID for the 'sub' parameter (or omit to use auto-generated service account)

Quick Start

Use the provided Python client for all API interactions:

from greenhouse_client import GreenhouseClient

client = GreenhouseClient()

# List all open jobs
jobs = client.get('/v3/jobs', params={'status': 'open'})

# Get applications for a specific job
applications = client.get_all('/v3/applications', params={'job_id': 12345})

# Get scheduled interviews for this week
interviews = client.get_all('/v3/scheduled_interviews', params={
    'starts_after': '2024-01-15T00:00:00Z',
    'starts_before': '2024-01-22T00:00:00Z'
})

The client handles:

• OAuth authentication via environment variables
• Automatic token generation and refresh
• Automatic pagination with get_all()
• Rate limiting with exponential backoff
• Error handling and retries

Common Query Workflows

Candidate Counting

User request: "How many candidates have applied for software engineer this week?"

Steps:

1. Find the job by searching job names
2. Calculate the date range (e.g., last 7 days)
3. Query applications filtered by job_id and created_after
4. Count results

See: references/common_queries.md → "Candidate Counting Queries" for complete examples

Candidate Status Lookup

User request: "What status is Jane Smith in?"

Steps:

1. Search candidates by name (fetch all or filter by updated_after)
2. Get their application IDs
3. Fetch each application to get current stage and job

Note: Greenhouse lacks direct name search; filter locally or use date ranges to limit scope.

See: references/common_queries.md → "Candidate Status Lookup" for optimization strategies

Interview Metrics

User request: "How many interviews are booked this week?"

Steps:

1. Calculate date range
2. Query /v3/scheduled_interviews with starts_after and starts_before
3. Count and optionally group by day, interviewer, or interview type

See: references/common_queries.md → "Interview Counting Queries" for examples

Pipeline Conversion Analysis

User request: "What is the passthrough rate from application review to phone screen for the product designer role?"

Steps:

1. Find the job by name
2. Get job stages to identify stage IDs and priorities
3. Fetch applications for the job (optionally filter by date range)
4. Count applications that reached each stage based on current_stage priority
5. Calculate conversion rate

Note: Greenhouse tracks current stage, not full history. For more accurate data, use scorecards as a proxy for stage completion.

See: references/common_queries.md → "Pipeline Conversion Analysis" for detailed approaches

Other Common Queries

The skill supports many other query types:

• Time-to-hire analysis: Average days from application to hire
• Source effectiveness: Which sources bring the most candidates
• Recruiter performance: Candidates sourced by specific recruiters
• Scorecard analysis: Average interview ratings

See: references/common_queries.md for complete patterns and code examples

When to Use Which Reference

references/api_endpoints.md

Use when: You need to understand what endpoints are available or what parameters/filters they support.

Contents:

• All major endpoints organized by category
• Query parameters and filters
• Response structures
• Common response fields
• Pagination and rate limiting details

Examples:

• "What filters can I use on the applications endpoint?"
• "How do I search for interviews by date?"
• "What fields are returned in a candidate object?"

references/schema.md

Use when: You need detailed field definitions or relationships between data models.

Contents:

• Complete schema for Candidate, Application, Job, Interview, Scorecard, User objects
• Field types and descriptions
• Relationships between objects (via ID references)
• Enum values (application

...