Greenhouse Harvest API Skill

An AI agent skill for querying and analyzing recruitment data from the Greenhouse Harvest API v3 conversationally.

What This Skill Does

Transform complex Greenhouse API queries into simple conversational requests. Instead of navigating through the Greenhouse UI or writing API calls manually, ask the agent questions in natural language:

• "How many candidates applied for software engineer this week?"
• "What status is Jane Smith in?"
• "How many interviews are booked tomorrow?"
• "What's the passthrough rate from phone screen to onsite for the product designer role?"
• "Which source has brought the most candidates this quarter?"
• "What's the average time to hire for backend engineers?"

Installation

1. Install the skill via skills.sh:

   npx skills add tcn33/greenhouse-harvest-skill
   

2. Alternatively, install the skill in Claude Code:

   claude skill install greenhouse-harvest.skill
   

   Or in Gemini-CLI:

   gemini skills install https://github.com/tcn33/greenhouse-harvest-skill
   

3. Install Python dependencies:

   cd ~/.claude/skills/greenhouse-harvest  # Or wherever the skill is installed
   pip install -r requirements.txt
   

4. Set your Greenhouse OAuth credentials as environment variables:

   export GREENHOUSE_CLIENT_ID="your-client-id"
   export GREENHOUSE_CLIENT_SECRET="your-client-secret"
   export GREENHOUSE_USER_ID="your-user-id"  # Optional
   

   To make this permanent, add them to your ~/.zshrc or ~/.bashrc:

   echo 'export GREENHOUSE_CLIENT_ID="your-client-id"' >> ~/.zshrc
   echo 'export GREENHOUSE_CLIENT_SECRET="your-client-secret"' >> ~/.zshrc
   echo 'export GREENHOUSE_USER_ID="your-user-id"' >> ~/.zshrc  # Optional
   source ~/.zshrc
   

Getting Your OAuth Credentials

1. Log into Greenhouse
2. Navigate to: Configure → Dev Center → API Credential Management
3. Create a new credential and select "Harvest V3 (OAuth)"
4. Copy the Client ID and Client Secret
5. Optionally specify a User ID for the 'sub' parameter (or omit to use an auto-generated service account)
6. Set the credentials as environment variables

Requirements

• Claude Code/Gemini CLI/your choice of AI agent
• Python 3.7+
• requests library (installed automatically when the skill runs)
• Valid Greenhouse Harvest API v3 OAuth credentials with read permissions

Usage Examples

Once installed, simply ask the agent questions about your recruitment data:

Candidate Metrics

How many candidates have applied this month?
How many active applications do we have for the Senior Developer role?
Show me candidates who applied in the last 7 days

Status Lookups

What status is John Smith in?
Where is Sarah Jones in the hiring pipeline?
Show me the current stage for candidate ID 12345

Interview Scheduling

How many interviews are scheduled for tomorrow?
How many interviews does Alice have this week?
Show me all phone screens happening next Monday

Pipeline Analytics

What's the conversion rate from application review to phone screen?
Calculate the passthrough rate for the Engineering Manager role
Show me the drop-off between each stage for Product Designer

Performance Metrics

What's the average time to hire for engineering roles?
Which recruiter has sourced the most candidates this quarter?
What are the top 5 sources for candidates this year?
Show me average interview scores for the PM role

What's Included

The skill packages:

• greenhouse_client.py - Python API client with OAuth authentication, automatic token refresh, pagination, and error handling
• requirements.txt - Python package dependencies
• api_endpoints.md - Comprehensive endpoint documentation
• schema.md - Detailed data models and field definitions
• common_queries.md - Code patterns for common query types

Features

• OAuth 2.0 authentication with automatic token generation and refresh
• Automatic pagination for large datasets
• Rate limiting with exponential backoff
• Intelligent caching strategies for reference data
• Date range filtering for efficient queries
• Handles missing/null data gracefully
• Timezone-aware timestamp processing

Permissions Required

Your Greenhouse OAuth credentials need read access to:

• Candidates
• Applications
• Jobs
• Scheduled Interviews
• Scorecards
• Users
• Departments and Offices

Troubleshooting

"OAuth credentials not provided" Error

Make sure the required environment variables are set:

echo $GREENHOUSE_CLIENT_ID
echo $GREENHOUSE_CLIENT_SECRET
echo $GREENHOUSE_USER_ID  # Optional

If empty, set them and restart your shell.

Authentication Failed (401 Error)

If you receive authentication errors:

• Verify your Client ID and Client Secret are correct
• Check if your OAuth credentials have been rotated (old secrets expire after 1 week)
• Ensure your credentials have

...