Skip to main content

Greenhouse

Greenhouse is a leading Applicant Tracking System (ATS) and recruiting platform that helps organizations streamline their hiring process. It provides comprehensive tools for managing candidates, tracking applications through interview pipelines, scheduling interviews, collecting feedback via scorecards, extending offers, and analyzing recruiting metrics.

Authentication Types​

Greenhouse supports 2 authentication methods:

  • OAuth 2.0 (Client Credentials) - Create OAuth credentials in Greenhouse for server-to-server authentication.

    • Pros: Secure, automatic token refresh, granular scope control, production-ready
    • Cons: Requires Site Admin access to set up, tokens expire after 1 hour
    • Best for: Production integrations, automated workflows, compliance requirements

  • API Key - Use a Harvest API key for all requests.

    • Pros: Simple setup, no token expiration handling needed
    • Cons: Static credential, requires rotation management, binary access control (all or nothing per endpoint)
    • Best for: Development, testing, single-user scenarios

General Settings​

Before using the connector, you need to configure your Greenhouse base URL:

  • Greenhouse API Version - The connector uses Harvest API v3 (https://harvest.greenhouse.io/v3)
tip

Greenhouse Harvest API provides read and write access to most data in your Greenhouse account. Make sure to grant only the scopes and endpoints your integration needs.

Setting up OAuth 2.0 (Client Credentials)​

OAuth 2.0 with Client Credentials flow is the recommended authentication method for custom integrations. You'll need Site Admin privileges.

  1. Log in to your Greenhouse account with Site Admin access

  2. Navigate to Configure → Dev Center → API Credential Management

  3. Click Create New Credential

  4. Select Harvest v3 as the API type

  5. Select OAuth 2.0 as the authentication method

  6. Fill in the credential details:

    • Credential Name: Give it a descriptive name (e.g., "Webrix AI Integration")
    • Description: Optional description of what this integration does

  7. Click Create

  8. After creation, you'll see your Client ID and Client Secret - copy both immediately

    caution

    The Client Secret is only shown once. Store it securely - if you lose it, you'll need to create new credentials.

  9. Configure endpoint permissions:

    • Click Manage Permissions next to your new credential
    • Grant access to the specific API endpoints your integration needs
    • For full functionality, grant access to all Harvest v3 endpoints

  10. In Webrix, go to Integrations → New → Built-in

  11. Select Greenhouse and click Use

  12. Under Authentication Type, select OAuth 2.0 (Client Credentials)

  13. Paste your Client ID in the Client ID field

  14. Paste your Client Secret in the Client Secret field

  15. Click Save Changes

  16. Click Connect to test the authentication

tip

OAuth 2.0 access tokens expire after 1 hour. The integration will automatically request new tokens using the client credentials when needed.

Setting up API Key​

API Keys provide simpler authentication but require manual management. You'll need Site Admin privileges.

  1. Log in to your Greenhouse account with Site Admin access

  2. Navigate to Configure → Dev Center → API Credential Management

  3. Click Create New Credential

  4. Select Harvest v3 (or Harvest v1 for legacy) as the API type

  5. Select API Key as the authentication method

  6. Fill in the credential details:

    • Credential Name: Give it a descriptive name (e.g., "Webrix Integration Key")
    • Description: Optional description

  7. Click Create

  8. After creation, copy the API Key shown

    caution

    The API Key is only shown once. Store it securely - if you lose it, you'll need to generate a new key.

  9. Configure endpoint permissions:

    • Click Manage Permissions next to your new credential
    • Grant access to the specific API endpoints your integration needs
    • Access is binary per endpoint: you either have full access or no access

  10. In Webrix:

    • Select API Key as the authentication type
    • Paste your API Key
    • Click Save Changes
tip

API Keys never expire but should be rotated regularly as a security best practice. You can create multiple API keys for different integrations.

Available Operations​

The Greenhouse connector provides 28 tools across 7 categories:

Candidates (6 tools)​

  • List Candidates - Search and filter candidates with cursor-based pagination
  • Get Candidate - Retrieve complete candidate profile including applications and attachments
  • Create Candidate - Add new candidates with contact information and tags
  • Update Candidate - Edit candidate profiles and contact details
  • Add Candidate Note - Record notes and observations about candidates
  • Add Candidate Attachment - Upload resumes, cover letters, and other documents

Applications (7 tools)​

  • List Applications - Browse applications with filtering by job, candidate, status, or date
  • Get Application - Retrieve detailed application information and history
  • Create Application - Submit a candidate's application to a specific job
  • Advance Application - Move applications to the next stage in the pipeline
  • Reject Application - Reject applications with reasons and optional rejection emails
  • Hire Application - Mark applications as hired and fill job openings
  • Move Application to Different Job - Transfer applications between jobs

Jobs & Openings (5 tools)​

  • List Jobs - Browse all jobs with filtering by status, department, or office
  • Get Job - Retrieve complete job details including stages and hiring team
  • List Job Posts - View public job board postings and internal postings
  • List Job Openings - Get all available positions for a specific job
  • Get Job Hiring Team - Retrieve the team members responsible for a job

Interviews & Scorecards (4 tools)​

  • List Scheduled Interviews - View upcoming and past interviews across all applications
  • Create Scheduled Interview - Schedule new interviews with date, location, and interviewers
  • List Scorecards - Browse interview feedback and evaluations
  • Get Scorecard - Retrieve detailed scorecard with questions, ratings, and recommendations

Offers (2 tools)​

  • List Offers - Browse all job offers with date filtering
  • Get Current Offer for Application - Retrieve the active offer for a specific application

Organization & Settings (4 tools)​

  • List Users - View all Greenhouse users and team members
  • List Departments - Get organizational departments
  • List Offices - Get office locations and regions
  • List Custom Fields - View custom field definitions for candidates, applications, and jobs

Tags, Activity & Reference Data (4 tools)​

  • List Candidate Tags - Get all available candidate tags
  • Get Activity Feed - Retrieve audit log of all system activities
  • List Rejection Reasons - Get configured rejection reasons for applications
  • List Sources - View candidate sources and recruiting channels

Common Use Cases​

Candidate Sourcing Workflow​

  1. Use Create Candidate to add a new candidate
  2. Use Add Candidate Attachment to upload their resume
  3. Use Create Application to submit them for a job
  4. Track their progress through the pipeline

Interview Scheduling​

  1. Use List Jobs to find the job
  2. Use Get Job to see available interview stages
  3. Use Create Scheduled Interview to schedule interviews
  4. Use List Scorecards to review feedback after interviews

Application Management​

  1. Use List Applications to find applications in a specific stage
  2. Use Advance Application to move qualified candidates forward
  3. Use Reject Application for candidates who don't meet requirements
  4. Use Hire Application when a candidate accepts an offer

Reporting & Analytics​

  1. Use Get Activity Feed to track all recruiting activities
  2. Use List Applications with date filters to analyze pipeline metrics
  3. Use List Scorecards to evaluate interviewer feedback quality
  4. Use List Sources to measure recruiting channel effectiveness

Troubleshooting​

"Unauthorized" or 401 Errors​

Cause: Invalid credentials or expired access token.

Solution:

  1. For OAuth: Verify your Client ID and Client Secret are correct
  2. For API Key: Verify your API key is correctly entered and not revoked
  3. Check that the credentials haven't been deleted in Greenhouse
  4. Ensure the credentials have not expired or been rotated

"Forbidden" or 403 Errors​

Cause: Your credentials don't have permission to access a specific endpoint.

Solution:

  1. Go to Greenhouse → Configure → Dev Center → API Credential Management
  2. Click Manage Permissions next to your credential
  3. Grant access to the required endpoint
  4. Note that access is binary per endpoint - you need explicit permission

"Not Found" or 404 Errors​

Cause: The requested resource doesn't exist or you don't have access.

Solution:

  1. Verify the ID you're using is correct
  2. Check that the resource hasn't been deleted
  3. Ensure your credential has permission to view that resource type

Rate Limit Exceeded (429 Errors)​

Cause: You've exceeded Greenhouse's API rate limits.

Solution:

  1. Check the X-RateLimit-Limit and X-RateLimit-Remaining headers
  2. Implement exponential backoff and retry logic
  3. Use the X-RateLimit-Reset header to know when to retry
  4. Contact Greenhouse if you need higher rate limits for production use

"Validation Error" or 422 Errors​

Cause: Invalid data in your request.

Solution:

  1. Review the error message for specific field issues
  2. Ensure required fields are included
  3. Verify data types match expected formats (e.g., ISO-8601 for dates)
  4. Check that IDs reference valid existing resources

OAuth Token Refresh Failures​

Cause: Client credentials are invalid or permissions changed.

Solution:

  1. Verify Client ID and Client Secret are still valid
  2. Check that the OAuth credential wasn't deleted or regenerated
  3. Re-enter the credentials in Webrix
  4. Test the connection again

Security Best Practices​

  1. Principle of Least Privilege: Grant only the endpoint permissions your integration needs
  2. Credential Rotation: Regularly rotate API keys (every 90 days recommended)
  3. Secure Storage: Never commit credentials to source control or share them via unencrypted channels
  4. Monitor Access: Review the Activity Feed regularly to audit API usage
  5. User Attribution: Use OAuth for production to track which user performed each action
  6. Separate Environments: Use different credentials for development, staging, and production

API Rate Limits​

Greenhouse enforces rate limits per 10-second windows:

  • The exact limit is returned in the X-RateLimit-Limit header
  • Remaining requests are in the X-RateLimit-Remaining header
  • When limit is exceeded, requests return HTTP 429
  • The Retry-After header indicates when you can retry
  • Approved partners may have higher limits

Additional Resources​

Differences Between Harvest v1 and v3​

If you're familiar with Harvest v1 or v2, note these key differences in v3:

  • Pagination: v3 uses cursor-based pagination instead of offset-based
  • Authentication: v3 supports OAuth 2.0 Client Credentials flow
  • Filtering: Enhanced filtering with created_after, updated_after, and other parameters
  • Performance: Improved performance for large data sets
  • Scopes: More granular scope control for OAuth integrations
tip

This connector uses Harvest API v3. If you need v1 compatibility, please contact support.