Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Greenhouse IO

Gem Version Build Status Test Coverage Dependency Status

A Ruby interface to's API (requires Ruby 1.9.3 or greater).


Add the gem to your application's Gemfile:

gem 'greenhouse_io'

Or install it yourself as:

$ gem install

API Documentation

Documentation for the Harvest and Job Board web APIs can be found at


You can assign default configuration values when using this gem.
Here is an example config/initializers/greenhouse_io.rb file used in a Rails application:

GreenhouseIo.configure do |config|
	config.symbolize_keys = true # set response keys as strings or symbols, default is false
	config.organization = 'General Assembly'
	config.api_token = ENV['GREENHOUSE_API_TOKEN']


Greenhouse's two APIs, Harvest and Job Board, can now be accessed through the gem. The GreenhouseIo::JobBoard is nearly identical to the old GreenhouseIo::API class. GreenhouseIo::Client connects to the new Harvest API.


Creating an instance of the JobBoard client:

gh ="api_token", organization: "your_organization")

If you've configured the gem with a default organization and api_token, then you can just instantiate the class.

gh =

api_token is only required for #apply_to_job and organization is also optional during initialization if an organization is passed in during method requests.

Fetching Office Data

gh.offices(organization: 'different_organization')
# returns a hash containing all of the organization's department and jobs grouped by office, organization: 'different_organization')
# returns a hash containing the departments and jobs of a specific office

Fetching Department Data

gh.departments(organization: 'different_organizaton')
gh.department(id, organization: 'different_organization')

Fetching Job Data 'true')
# includes the job description in the response 'different_organization')
gh.job(id, questions: true)
# returns the specified job and the array of questions on the application
gh.job(id, organization: 'different_organization')

Submitting a Job Application

This is the only API method that requires an API token from Greenhouse


# form_parameter_hash should match the questions array of a given job opening
# there should be a hidden input with name id in your form that
# has the value of the job ID on


Creating an instance of the API client:

gh_client ="api_token")

If you've configured the gem with a default api_token, then you can just instantiate the class.

gh_client =

Listing candidates


Creating a candidate note

Use this method to attach a new note to a candidate.

candidate_id = 4567
author_id = 123 # ID of the user who wrote this note
note = {
  :user_id => 123,
  :message => "This candidate has very strong opinions about Node.JS.",
  :visibility => "public"

gh_client.create_candidate_note(candidate_id, note, author_id)


Rate limit and rate limit remaining are available after making an API request with an API client:

gh_client.rate_limit # => 20
gh_client.rate_limit_remaining  # => 20


All GreenhouseIo::Client API methods accept :page and :per_page options to get specific results of a paginated response from Greenhouse.

gh_client.offices(id, page: 1, per_page: 2)

You can determine the last page and next page by looking at the link header from the last response:

# => '<>; rel="next",<>; rel="last"'

You'll need to manually parse the next and last links to tell what the next or final page number will be.

Available methods

Methods for which an id is optional:

  • offices
  • departments
  • candidates
  • applications
  • jobs
  • users
  • sources
  • all_scorecards
  • offers

Methods for which an id is required:

  • activity_feed (requires a candidate ID)
  • scorecards (requires an application ID)
  • scheduled_interviews (requires an application ID)
  • offers_for_application (requires an application ID)
  • current_offer_for_application (requires an application ID)
  • stages (requires a job ID)
  • job_post (requires a job ID)
  • create_candidate_note (requires a candidate ID)


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Contributions are always welcome!