NAV
shell ruby

Introduction

  _          _ _             
 | |__   ___| | | ___        
 | '_ \ / _ \ | |/ _ \       
 | | | |  __/ | | (_) |      
 |_| |_|\___|_|_|\___/     _
 __      _____  _ __| | __| |
 \ \ /\ / / _ \| '__| |/ _` |
  \ V  V / (_) | |  | | (_| |
   \_/\_/ \___/|_|  |_|\__,_|

With Harvest, you have access to most of your Greenhouse data!

The Harvest API was designed to allow our customers to export their data from Greenhouse. However, it can also be used to…

  1. Update candidate information.
  2. Add attachments to candidate profiles.
  3. Advance, move, and reject applications.

We have usage examples for cURL (and soon, Ruby)! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

This documentation is open source! Feel free to leave feedback as issues in the GitHub repo or fork it and contribute changes!

Authentication

To authorize, use this code:

require 'base64'
api_token = 'a7183e1b7e9ab09b8a5cfa87d1934c3c'
credential = Base64.strict_encode64(api_token + ':')
# => "YTcxODNlMWI3ZTlhYjA5YjhhNWNmYTg3ZDE5MzRjM2M6"

headers = {
  "Authorization" => "Basic " + credential
}
# Note the trailing colon after the username (API token):
$ curl https://harvest.greenhouse.io/v1/candidates/ -u a7183e1b7e9ab09b8a5cfa87d1934c3c:
...

> GET /v1/candidates/ HTTP/1.1
> Host: harvest.greenhouse.io
> Authorization: Basic YTcxODNlMWI3ZTlhYjA5YjhhNWNmYTg3ZDE5MzRjM2M6

...

Harvest uses Basic Auth over HTTPS for authentication. The username is your Greenhouse API token and the password should be blank. Unauthenticated requests will return an HTTP 401 response.

Harvest API keys can be obtained in Greenhouse. In order to create a Harvest API key, a user must be granted the “Can manage ALL organization’s API Credentials” in the “Developer permission” section. That user can then go Configure >> Dev Center >> API Credential Management. From there, you can create a Harvest API key and choose which endpoints it may access.

Important Note: Users with Harvest API keys may access all the data in the endpoint. Access to data in Harvest is binary: everything or nothing. Harvest API keys should be given to internal developers with this understanding and to third parties with caution. Each key should only be allowed to access the endpoints it absolutely needs.

Authorization header

Your Authorization header should look like this:

Authorization: Basic YTcxODNlMWI3ZTlhYjA5YjhhNWNmYTg3ZDE5MzRjM2M6

Most HTTP clients will automatically use a given username and password to generate the required Authorization header. However, you may need to explicity set this header. The header has the following format:

Authorization: Basic <base64("username:password")>

Since only a username needs to be provided in our case, you’ll need to append a : (colon) to your Greenhouse API token and then Base64 encode the resulting string.

Setting credentials with cURL

If you’re making test API requests with cURL you can use the -u flag to set the username and password (which is blank). cURL will automatically generate the Authorization header.

Setting permissions for API Keys

You can specify which API endpoints your API keys have access to from the Greenhouse Dev Center. This will allow you to permit or deny access to each endpoint individually. Any API keys created before January 18th, 2017 will have full permissions to all API endpoints that existed at that time, but any new API keys created after that point will need to be explicitly granted the required endpoint permissions.

To add or remove endpoint permissions on an API key, go to the Dev Center in Greenhouse, click “API Credential Management,” then click “Manage Permissions” next to your Harvest API Key. From there, check or uncheck permissions for any endpoints.

Throttling

Status: 200 OK
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49

API requests are limited to the amount specified in the returned X-RateLimit-Limit header (per 10 seconds). Exceeding that limit will cause Harvest to return an HTTP 429 response. Check the X-RateLimit-Limit and X-RateLimit-Remaining headers to see how many more requests you are allowed until throttling kicks in. Note that the HTTP 429 response will exclude the X-RateLimit-Limit and X-RateLimit-Remaining headers.

Pagination

Example paging header

Link: <https://harvest.greenhouse.io/v1/candidates?page=2&per_page=2>; rel="next",
<https://harvest.greenhouse.io/v1/candidates?page=474&per_page=2>; rel="last"

API methods that return a collection of results are always paginated. Paginated results will include a Link (see RFC-5988) response header with the following information.

Note that when this header is not set, there is only one page, the first page, of results.

As of February 2017, we are transitioning to a new method for paging while maintaining backwards compatibility. Currently, the new method only supports providing a next link and is used by the following endpoints:

Validation

{
  "message": "Validation error",
  "errors": [
    {
        "message": "Must be one of: candidate, prospect",
        "field": "type"
    }
  ]
}

Methods that take input will validate all parameters. Any parameter that fails validation will trigger an error response with status HTTP 422. The response body will be a JSON object that includes a message as well as a list of fields that failed validation.

General considerations

Unless otherwise specified, API methods generally conform to the following:

Errors

Error CodeMeaning
401Unauthorized – Invalid Harvest API key. Check to make sure you’re passing it in via the Authorization header (Basic Auth)
403Forbidden – You do not have access to that record.
404Not Found – Resource not found
500Server Error – We had a problem with our server. Try again later or contact us: support@greenhouse.io

Activity Feed

The activity feed object

The activity feed is the list of activities on a candidate’s profile, including interviews, notes, and emails.

{
  "notes": [
    {
      "id": 12345,
      "created_at": "2014-03-26T20:11:40Z",
      "body": "Very mysterious.",
      "user": {
        "id": 512,
        "first_name": "Sayid",
        "last_name": "Jarrah",
        "name": "Sayid Jarrah",
        "employee_id": "12345"
      },
      "private": false,
      "visiblity": "public",
      "visibility": "public"
    }
  ],
  "emails": [
    {
      "id": 234675,
      "created_at": "2014-04-01T15:55:06Z",
      "subject": "Regarding your application",
      "body": "Hey John,  just wanted to touch base!",
      "to": "john.locke@example.com",
      "from": "boone.carlyle@example.com",
      "cc": "sam.smith@example.com",
      "user": {
        "id": 214,
        "first_name": "Boone",
        "last_name": "Carlyle",
        "name": "Boone Carlyle",
        "employee_id": "67890"
      }
    }
  ],
  "activities": [
    {
      "id": 6756789,
      "created_at": "2014-04-01T15:55:29Z",
      "subject": "Candidate Rejected",
      "body": "Reason: Lacking hustle\n\nThis candidate turned out to be problematic for us...",
      "user": {
        "id": 214,
        "first_name": "Boone",
        "last_name": "Carlyle",
        "name": "Boone Carlyle",
        "employee_id": "67890"
      }
    },
    {
      "id": 6757869,
      "created_at": "2014-03-26T20:26:38Z",
      "subject": "Candidate Stage Change",
      "body": "John Locke was moved into Recruiter Phone Screen for Accounting Manager on 03/27/2014 by Boone Carlyle",
      "user": {
        "id": 214,
        "first_name": "Boone",
        "last_name": "Carlyle",
        "name": "Boone Carlyle",
        "employee_id": "67890"
      }
    }
  ]
}

Noteworthy attributes

AttributeDescription
idThe internal Greenhouse ID of the activity feed note.
noteAn array of notes associated with this candidate.
emailAn array of emails sent to and from this candidate.
activityAn array of events associated with this candidate.
visibility*The visibility setting on the note. One of admin_only, public, or private.

* - Due to a legacy typo, the response includes the same value as visiblity. It is safe to ignore this value, but it is maintained for backward compatibility.

GET: Retrieve Activity Feed

curl 'https://harvest.greenhouse.io/v1/candidates/{id}/activity_feed' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

{
  "notes": [
    {
      "id": 12345,
      "created_at": "2014-03-26T20:11:40Z",
      "body": "Very mysterious.",
      "user": {
        "id": 512,
        "first_name": "Sayid",
        "last_name": "Jarrah",
        "name": "Sayid Jarrah",
        "employee_id": "12345"
      },
      "private": false,
      "visiblity": "public",
      "visibility": "public"
    }
  ],
  "emails": [
    {
      "id": 234675,
      "created_at": "2014-04-01T15:55:06Z",
      "subject": "Regarding your application",
      "body": "Hey John,  just wanted to touch base!",
      "to": "john.locke@example.com",
      "from": "boone.carlyle@example.com",
      "cc": "sam.smith@example.com",
      "user": {
        "id": 214,
        "first_name": "Boone",
        "last_name": "Carlyle",
        "name": "Boone Carlyle",
        "employee_id": "67890"
      }
    }
  ],
  "activities": [
    {
      "id": 6756789,
      "created_at": "2014-04-01T15:55:29Z",
      "subject": "Candidate Rejected",
      "body": "Reason: Lacking hustle\n\nThis candidate turned out to be problematic for us...",
      "user": {
        "id": 214,
        "first_name": "Boone",
        "last_name": "Carlyle",
        "name": "Boone Carlyle",
        "employee_id": "67890"
      }
    },
    {
      "id": 6757869,
      "created_at": "2014-03-26T20:26:38Z",
      "subject": "Candidate Stage Change",
      "body": "John Locke was moved into Recruiter Phone Screen for Accounting Manager on 03/27/2014 by Boone Carlyle",
      "user": {
        "id": 214,
        "first_name": "Boone",
        "last_name": "Carlyle",
        "name": "Boone Carlyle",
        "employee_id": "67890"
      }
    }
  ]
}

Retrieve a candidate’s activity feed.

HTTP Request

GET https://harvest.greenhouse.io/v1/candidates/{id}/activity_feed

URL Parameters

ParameterDescription
idThe ID of the candidate whose activity feed you want to retrieve.


See noteworthy response attributes.

Applications

The application object

Applications associate candidates with jobs. There are 2 kinds of applications: candidates and prospects. Candidate applications always have exactly 1 job. Prospect applications can have 0 or more jobs.

{
    "id": 985314,
    "candidate_id": 978031,
    "prospect": false,
    "applied_at": "2016-03-26T20:11:39.000Z",
    "rejected_at": "2016-08-17T21:08:29.686Z",
    "last_activity_at": "2016-08-27T16:13:15.000Z",
    "location": { 
        "address": "New York, New York, USA" 
    },
    "source": {
        "id": 1871,
        "public_name": "Happy Hour"
    },
    "credited_to": {
        "id": 4080,
        "first_name": "Kate",
        "last_name": "Austen",
        "name": "Kate Austen",
        "employee_id": "12345"
    },
    "rejection_reason": {
        "id": 8,
        "name": "Lacking skill(s)/qualification(s)",
        "type": {
            "id": 1,
            "name": "We rejected them"
        }
    },
    "rejection_details": {
        "custom_fields": {
            "custom_rejection_question_field": "Not a good fit"
        },
        "keyed_custom_fields": {
            "custom_rejection_question_field": {
                "name": "Was this candidate a good fit?",
                "type": "short_text",
                "value": "Not a good fit."
            }
        }
    },
    "jobs": [
        {
            "id": 123,
            "name": "Accounting Manager"
        }
    ],
    "status": "rejected",
    "current_stage": {
        "id": 62828,
        "name": "Recruiter Phone Screen"
    },
    "answers": [
        {
            "question": "Why do you want to work for us?",
            "answer": "I heard you're awesome!"
        },
        {
            "question": "How did you hear about this job?",
            "answer": "From a former colleague."
        }
    ],
    "prospect_detail": {
        "prospect_pool": null,
        "prospect_stage": null,
        "prospect_owner": null
    },
    "custom_fields": {
        "bio": "This is a bio",
        "birthday": "1992-01-27"
    },
    "keyed_custom_fields": {
        "date_of_birth": {
            "name": "Birthday",
            "type": "date",
            "value": "1992-01-27"
        },
        "bio": {
            "name": "Bio",
            "type": "long_text",
            "value": "This is a bio"
        }
    }
}

Noteworthy attributes

AttributeDescription
idApplication ID
prospectIf true, this is a prospect application which means that the associated person is a prospect and has not yet applied for this job.
statusOne of: active, rejected, hired.
jobsAn array containing the job that the candidate applied for.
candidate_idThe ID of the candidate who is applying for this job.
current_stageThe current stage that this application is in.
credited_to.idThe ID of the user who will receive credit for this application.
locationThe contents of the location question on a job post.
answersThe answers provided to the questions in the job post for this application. Array contains the text value of the question and answer. Answers are always plaintext strings. Booleans will return Yes or No.
custom_fieldsContains a hash of the custom fields configured for this resource. The properties in this hash reflect the active custom fields as of the time this method is called.
keyed_custom_fieldsThis contains the same information as custom_fields but formatted in a different way that includes more information. This will tell you the type of custom field data to expect, the text name of custom field, and the value. The key of this hash is the custom field’s immutable field key, which will not change even if the name of the custom field is changed in Greenhouse.

GET: List Applications

curl -X GET 'https://harvest.greenhouse.io/v1/applications'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
[
  {
    "id": 69306314,
    "candidate_id": 57683957,
    "prospect": false,
    "applied_at": "2017-09-29T12:56:05.244Z",
    "rejected_at": null,
    "last_activity_at": "2017-09-29T13:00:28.038Z",
    "location": { 
        "address": "New York, New York, USA" 
    },
    "source": {
        "id": 2,
        "public_name": "Jobs page on your website"
    },
    "credited_to": {
      "id": 4080,
      "first_name": "Kate",
      "last_name": "Austen",
      "name": "Kate Austen",
      "employee_id": "12345"
    },
    "rejection_reason": null,
    "rejection_details": null,
    "jobs": [
        {
            "id": 107761,
            "name": "UX Designer - Boston"
        }
    ],
    "status": "active",
    "current_stage": {
        "id": 767358,
        "name": "Application Review"
    },
    "answers": [
        {
            "question": "How did you hear about this job?",
            "answer": "Online Research"
        },
        {
            "question": "Website",
            "answer": "mytestwebsite.com"
        }
    ],
    "prospect_detail": {
        "prospect_pool": null,
        "prospect_stage": null,
        "prospect_owner": null
    },
    "custom_fields": {
        "application_custom_test": "Option 1"
    },
    "keyed_custom_fields": {
        "application_custom_test": {
            "name": "Application Custom Test",
            "type": "single_select",
            "value": "Option 1"
        }
    }
},
{
    "id": 69306509,
    "candidate_id": 57683957,
    "prospect": true,
    "applied_at": "2017-09-29T13:00:04.058Z",
    "rejected_at": null,
    "last_activity_at": "2017-09-29T13:08:19.111Z",
    "location": null,
    "source": {
        "id": 100674,
        "public_name": "Campus Job Fair"
    },
    "credited_to": {
        "id": 566819,
        "first_name": "Bob",
        "last_name": "Smith",
        "name": "Bob Smith",
        "employee_id": "ABC12345"
    },
    "rejection_reason": null,
    "rejection_details": null,
    "jobs": [
        {
            "id": 224587,
            "name": "Product Manager "
        },
        {
            "id": 109322,
            "name": "Web Developer "
        }
    ],
    "status": "hired",
    "current_stage": null,
    "answers": [
      {
          "question": "How did you hear about this job?",
          "answer": "Online Research"
      },
      {
          "question": "Website",
          "answer": "mytestwebsite.com"
      }
    ],
    "prospect_detail": {
        "prospect_pool": {
            "id": 227,
            "name": "Opted In: In-Person Event"
        },
        "prospect_stage": {
            "id": 826,
            "name": "In Discussion"
        },
        "prospect_owner": {
            "id": 92120,
            "name": "Greenhouse Admin"
        }
    },
    "custom_fields": {
        "application_custom_test": "Option 1"
    },
    "keyed_custom_fields": {
        "application_custom_test": {
            "name": "Application Custom Test",
            "type": "single_select",
            "value": "Option 1"
        }
    }
  }  
]

List all of an organization’s applications.

HTTP Request

GET https://harvest.greenhouse.io/v1/applications

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
created_beforeReturn only applications that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_afterReturn only applications that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
last_activity_afterReturn only applications where ‘last_activity_at’ is at or after this timestamp. Timestamp must be in in ISO-8601 format.
job_idIf supplied, only return applications that involve this job. Will return both candidates and prospects.
statusIf supplied, only return applications that match this status. Accepted values are active, converted, hired, and rejected. If anything else is used, an empty response will be returned rather than an error.


See noteworthy response attributes.

GET: Retrieve Application

curl -X GET 'https://harvest.greenhouse.io/v1/applications/{id}'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
{
    "id": 69306314,
    "candidate_id": 57683957,
    "prospect": false,
    "applied_at": "2017-09-29T12:56:05.244Z",
    "rejected_at": null,
    "last_activity_at": "2017-09-29T13:00:28.038Z",
    "location": { 
        "address": "New York, New York, USA" 
    },
    "source": {
        "id": 2,
        "public_name": "Jobs page on your website"
    },
    "credited_to": {
      "id": 4080,
      "first_name": "Kate",
      "last_name": "Austen",
      "name": "Kate Austen",
      "employee_id": "12345"
    },
    "rejection_reason": null,
    "rejection_details": null,
    "jobs": [
        {
            "id": 107761,
            "name": "UX Designer - Boston"
        }
    ],
    "status": "active",
    "current_stage": {
        "id": 767358,
        "name": "Application Review"
    },
    "answers": [
        {
            "question": "How did you hear about this job?",
            "answer": "Online Research"
        },
        {
            "question": "Website",
            "answer": "mytestwebsite.com"
        }
    ],
    "prospect_detail": {
        "prospect_pool": null,
        "prospect_stage": null,
        "prospect_owner": null
    },
    "custom_fields": {
        "application_custom_test": "Option 1"
    },
    "keyed_custom_fields": {
        "application_custom_test": {
            "name": "Application Custom Test",
            "type": "single_select",
            "value": "Option 1"
        }
    }
}

Retrieve an application by its id.

HTTP Request

GET https://harvest.greenhouse.io/v1/applications/{id}

URL parameters

ParameterDescription
idID of the application to retrieve


See noteworthy response attributes.

DELETE: Delete Application

curl -X DELETE 'https://harvest.greenhouse.io/v1/applications/{id}'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above returns a JSON response, structured like this:

{
  "message": "Application 29622362 has been deleted."
}

Delete an application by id. Note that only candidate applications can be deleted, you cannot delete a prospect application.

HTTP Request

DELETE https://harvest.greenhouse.io/v1/applications/{id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.


See noteworthy response attributes.

PATCH: Update Application

curl -X PATCH 'https://harvest.greenhouse.io/v1/applications/{id}'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "source_id": 16,
  "referrer": {
    "type": "id",
    "value": 123
  }
}

The above returns a JSON response, structured like this:

{
  "id": 69306314,
  "candidate_id": 57683957,
  "prospect": false,
  "applied_at": "2017-09-29T12:56:05.244Z",
  "rejected_at": null,
  "last_activity_at": "2017-09-29T13:00:28.038Z",
  "location": { 
      "address": "New York, New York, USA" 
  },
  "source": {
      "id": 2,
      "public_name": "Jobs page on your website"
  },
  "credited_to": {
    "id": 4080,
    "first_name": "Kate",
    "last_name": "Austen",
    "name": "Kate Austen",
    "employee_id": "12345"
  },
  "rejection_reason": null,
  "rejection_details": null,
  "jobs": [
      {
          "id": 107761,
          "name": "UX Designer - Boston"
      }
  ],
  "status": "active",
  "current_stage": {
      "id": 767358,
      "name": "Application Review"
  },
  "answers": [
      {
          "question": "How did you hear about this job?",
          "answer": "Online Research"
      },
      {
          "question": "Website",
          "answer": "mytestwebsite.com"
      }
  ],
  "prospect_detail": {
      "prospect_pool": null,
      "prospect_stage": null,
      "prospect_owner": null
  },
  "custom_fields": {
      "application_custom_test": "Option 1"
  },
  "keyed_custom_fields": {
      "application_custom_test": {
          "name": "Application Custom Test",
          "type": "single_select",
          "value": "Option 1"
      }
  }
}

Update this application. The response is populated with the application’s information which will reflect its new state. You can update applications whose status is active, rejected, or hired.

HTTP Request

PATCH https://harvest.greenhouse.io/v1/applications/{id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
source_idNointegerThe ID of the application’s source
referrerNoobjectAn object representing the referrer
referrer[type]NostringA string representing the type of referrer: 'id’, 'email’, or 'outside’
referrer[value]NostringThe id of the user who made the referral (not the referrer id)
custom_fields[]Nocustom_fieldArray of hashes containing new custom field values. Passing an empty array does nothing.

POST: Advance Application

curl -X POST 'https://harvest.greenhouse.io/v1/applications/{id}/advance'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "from_stage_id": 123
}

The above returns a JSON response, structured like this:

{
  "id": 69306314,
  "candidate_id": 57683957,
  "prospect": false,
  "applied_at": "2017-09-29T12:56:05.244Z",
  "rejected_at": null,
  "last_activity_at": "2017-09-29T13:00:28.038Z",
  "location": { 
      "address": "New York, New York, USA" 
  },
  "source": {
      "id": 2,
      "public_name": "Jobs page on your website"
  },
  "credited_to": {
    "id": 4080,
    "first_name": "Kate",
    "last_name": "Austen",
    "name": "Kate Austen",
    "employee_id": "12345"
  },
  "rejection_reason": null,
  "rejection_details": null,
  "jobs": [
      {
          "id": 107761,
          "name": "UX Designer - Boston"
      }
  ],
  "status": "active",
  "current_stage": {
      "id": 456,
      "name": "Phone Interview"
  },
  "answers": [
      {
          "question": "How did you hear about this job?",
          "answer": "Online Research"
      },
      {
          "question": "Website",
          "answer": "mytestwebsite.com"
      }
  ],
  "prospect_detail": {
      "prospect_pool": null,
      "prospect_stage": null,
      "prospect_owner": null
  },
  "custom_fields": {
      "application_custom_test": "Option 1"
  },
  "keyed_custom_fields": {
      "application_custom_test": {
          "name": "Application Custom Test",
          "type": "single_select",
          "value": "Option 1"
      }
  }
}

Move this application to the next stage. The response is populated with the application’s information which will reflect its new state. Note that only applications in the active state can be advanced.

HTTP Request

POST https://harvest.greenhouse.io/v1/applications/{id}/advance

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
from_stage_idYesintegerThe ID of the job stage this application is currently in.

POST: Move Application (Different Job)

curl -X POST 'https://harvest.greenhouse.io/v1/applications/{id}/transfer_to_job'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "new_job_id": 123456,
  "new_stage_id": 234567
}

The above returns a JSON response, structured like this:

{
  "id": 69306314,
  "candidate_id": 57683957,
  "prospect": false,
  "applied_at": "2017-09-29T12:56:05.244Z",
  "rejected_at": null,
  "last_activity_at": "2017-09-29T13:00:28.038Z",
  "location": { 
      "address": "New York, New York, USA" 
  },
  "source": {
      "id": 2,
      "public_name": "Jobs page on your website"
  },
  "credited_to": {
    "id": 4080,
    "first_name": "Kate",
    "last_name": "Austen",
    "name": "Kate Austen",
    "employee_id": "12345"
  },
  "rejection_reason": null,
  "rejection_details": null,
  "jobs": [
      {
          "id": 123456,
          "name": "UX Designer - Boston"
      }
  ],
  "status": "active",
  "current_stage": {
      "id": 234567,
      "name": "Application Review"
  },
  "answers": [
      {
          "question": "How did you hear about this job?",
          "answer": "Online Research"
      },
      {
          "question": "Website",
          "answer": "mytestwebsite.com"
      }
  ],
  "prospect_detail": {
      "prospect_pool": null,
      "prospect_stage": null,
      "prospect_owner": null
  },
  "custom_fields": {
      "application_custom_test": "Option 1"
  },
  "keyed_custom_fields": {
      "application_custom_test": {
          "name": "Application Custom Test",
          "type": "single_select",
          "value": "Option 1"
      }
  }
}

Move this application to any stage on a different job. If new_stage_id is omitted, the initial stage of the new job will be selected. Prospect applications can’t be moved in this way.

HTTP Request

POST https://harvest.greenhouse.io/v1/applications/{id}/transfer_to_job

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
new_job_idYesintegerThe ID of the job to which this application should be transferred
new_stage_idNointegerThe stage on the destination job this application should be placed in. If this is omitted, the application will be sent to the job’s initial stage


See noteworthy response attributes.

POST: Move Application (Same Job)

curl -X POST 'https://harvest.greenhouse.io/v1/applications/{id}/move'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "from_stage_id": 1,
  "to_stage_id": 2
}

The above returns a JSON response, structured like this:

{
  "id": 48206478,
  "candidate_id": 36952451,
  "prospect": false,
  "applied_at": "2017-02-01T14:26:02.282Z",
  "rejected_at": null,
  "last_activity_at": "2017-02-01T14:51:12.670Z",
  "location": { 
    "address": "New York, New York, USA" 
  },
  "source": {
    "id": 33,
    "public_name": "Glassdoor"
  },
  "credited_to": null,
  "rejection_reason": null,
  "rejection_details": null,
  "jobs": [
    {
      "id": 211706,
      "name": "Community Manager - New York"
    }
  ],
  "status": "active",
  "current_stage": {
    "id": 1551142,
    "name": "Offer"
  },
  "answers": [
    {
      "question": "How many years experience do you have?",
      "answer": "2-4"
    },
    {
      "question": "Can do you the travel required for this job?",
      "answer": "Yes"
    }
  ],
  "prospect_detail": {
    "prospect_pool": null,
    "prospect_stage": null,
    "prospect_owner": null
  },
  "custom_fields": {
    "current_title": "Community Manager",
    "requires_visa_sponsorship?": false
  },
  "keyed_custom_fields": {
    "current_title": {
      "name": "Current Title",
      "type": "short_text",
      "value": "Community Manager"
    },
    "requires_visa_sponsorship_": {
      "name": "Requires visa sponsorship?",
      "type": "boolean",
      "value": false
    }
  }
}

Move this application from one stage to another. An application can only be moved between stages on the same job. The response is populated with the application’s information which will reflect its new state. Note that only applications in the active state can be moved.

HTTP Request

POST https://harvest.greenhouse.io/v1/applications/{id}/move

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
from_stage_idYesintegerThe ID of the job stage this application is currently in.
to_stage_idYesintegerThe ID of the job stage this application should be moved to.


See noteworthy response attributes.

POST: Hire Application

curl -X POST 'https://harvest.greenhouse.io/v1/applications/{id}/hire'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "start_date": "2017-03-15",
  "opening_id": 454,
  "close_reason_id": 43432
}

The above returns a JSON response, structured like this:

{
  "id": 48206478,
  "candidate_id": 36952451,
  "prospect": false,
  "applied_at": "2017-02-01T14:26:02.282Z",
  "rejected_at": null,
  "last_activity_at": "2017-02-01T14:51:12.670Z",
  "location": { 
    "address": "New York, New York, USA" 
  },
  "source": {
    "id": 33,
    "public_name": "Glassdoor"
  },
  "credited_to": null,
  "rejection_reason": null,
  "rejection_details": null,
  "jobs": [
    {
      "id": 211706,
      "name": "Community Manager - New York"
    }
  ],
  "status": "hired",
  "current_stage": null,
  "answers": [
    {
      "question": "How many years experience do you have?",
      "answer": "2-4"
    },
    {
      "question": "Can do you the travel required for this job?",
      "answer": "Yes"
    }
  ],
  "prospect_detail": {
    "prospect_pool": null,
    "prospect_stage": null,
    "prospect_owner": null
  },
  "custom_fields": {
    "current_title": "Community Manager",
    "requires_visa_sponsorship?": false
  },
  "keyed_custom_fields": {
    "current_title": {
      "name": "Current Title",
      "type": "short_text",
      "value": "Community Manager"
    },
    "requires_visa_sponsorship_": {
      "name": "Requires visa sponsorship?",
      "type": "boolean",
      "value": false
    }
  }
}

Hire this application. The application must not be a prospect and all approvals for the job and offer must have occurred.

HTTP Request

POST https://harvest.greenhouse.io/v1/applications/{id}/hire

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
start_dateNo*stringThe start_date of the employee. Must be in the format YYYY-MM-DD
opening_idNointegerAn opening ID to fill with this hire. This is the unique Greenhouse id of the opening (id in the openings endpoint) and not the human readable opening id text. If no opening is provided one will be selected.
close_reason_idNointegerThe close reason to assign to the opening that will be closed with this hire.


Note that “current_stage” in the response JSON is null. A hired application no longer has a current stage.

See noteworthy response attributes.

POST: Reject Application

curl -X POST 'https://harvest.greenhouse.io/v1/applications/{id}/reject'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "rejection_reason_id": 815,
  "notes": "The prospect is not qualified for this position.",
  "rejection_email": {
    "send_email_at": "2014-03-26T20:11:39Z",
    "email_template_id": 42
  }
}

The above returns a JSON response, structured like this:

{
  "id": 985314,
  "candidate_id": 978031,
  "prospect": false,
  "applied_at": "2016-03-26T20:11:39.000Z",
  "rejected_at": "2016-08-17T21:08:29.686Z",
  "last_activity_at": "2016-08-27T16:13:15.000Z",
  "location": { 
    "address": "New York, New York, USA" 
  },
  "source": {
    "id": 1871,
    "public_name": "Happy Hour"
  },
  "credited_to": {
    "id": 4080,
    "first_name": "Kate",
    "last_name": "Austen",
    "name": "Kate Austen",
    "employee_id": "12345"
  },
  "rejection_reason": {
    "id": 815,
    "name": "The prospect is not qualified for this position.",
    "type": {
      "id": 1,
      "name": "We rejected them"
    }
  },
"rejection_details": {
  "custom_fields": {
      "custom_rejection_question_field": "Not a good fit"
  },
  "keyed_custom_fields": {
      "custom_rejection_question_field": {
          "name": "Was this candidate a good fit?",
          "type": "short_text",
          "value": "This candidate wasn't a good fit."
      }
  }
  "jobs": [
    {
      "id": 123,
      "name": "Accounting Manager"
    }
  ],
  "status": "rejected",
  "current_stage": {
    "id": 62828,
    "name": "Recruiter Phone Screen"
  },
  "answers": [
    {
      "question": "Why do you want to work for us?",
      "answer": "I heard you're awesome!"
    },
    {
      "question": "How did you hear about this job?",
      "answer": "From a former colleague."
    }
  ],
  "prospect_detail": {
      "prospect_pool": null,
      "prospect_stage": null,
      "prospect_owner": null
  },
  "custom_fields": {
    "bio": "This is a bio",
    "birthday": "1992-01-27"
  },
  "keyed_custom_fields": {
    "date_of_birth": {
      "name": "Birthday",
      "type": "date",
      "value": "1992-01-27"
    },
    "bio": {
      "name": "Bio",
      "type": "long_text",
      "value": "This is a bio"
    }
  }
}

Reject this application. The response is populated with the application’s information which will reflect its new state. Note that only applications in the active state can be rejected.

HTTP Request

POST https://harvest.greenhouse.io/v1/applications/{id}/reject

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
rejection_reason_idNointegerThe ID of the reason why this application was rejected.
notesNostringNotes on why this application was rejected. These will be added to the activity feed.
rejection_emailNohashAn email will be sent to the candidate notifying them of this rejection.
rejection_email.send_email_atNostringThe rejection email will be delayed until this time.
rejection_email.email_template_idYes, if sending rejection_emailstringThe template the to use for the rejection email.

POST: Unreject Application

curl -X POST 'https://harvest.greenhouse.io/v1/applications/{id}/unreject'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command requires an empty JSON body:

{}

The above returns a JSON response, structured like this:

{
  "id": 69306314,
  "candidate_id": 57683957,
  "prospect": false,
  "applied_at": "2017-09-29T12:56:05.244Z",
  "rejected_at": null,
  "last_activity_at": "2017-09-29T13:00:28.038Z",
  "location": { 
      "address": "New York, New York, USA" 
  },
  "source": {
      "id": 2,
      "public_name": "Jobs page on your website"
  },
  "credited_to": {
    "id": 4080,
    "first_name": "Kate",
    "last_name": "Austen",
    "name": "Kate Austen",
    "employee_id": "12345"
  },
  "rejection_reason": null,
  "rejection_details": null,
  "jobs": [
      {
          "id": 107761,
          "name": "UX Designer - Boston"
      }
  ],
  "status": "active",
  "current_stage": {
      "id": 767358,
      "name": "Application Review"
  },
  "answers": [
      {
          "question": "How did you hear about this job?",
          "answer": "Online Research"
      },
      {
          "question": "Website",
          "answer": "mytestwebsite.com"
      }
  ],
  "prospect_detail": {
      "prospect_pool": null,
      "prospect_stage": null,
      "prospect_owner": null
  },
  "custom_fields": {
      "application_custom_test": "Option 1"
  },
  "keyed_custom_fields": {
      "application_custom_test": {
          "name": "Application Custom Test",
          "type": "single_select",
          "value": "Option 1"
      }
  }

An unsuccessful response:

{
  "errors": [
    {
      "message": "Application must be 'rejected', is currently 'active'"
    }
  ]
}

Unreject this application. The response is populated with the application in its new state. Note that only applications in the rejected state can be unrejected.

HTTP Request

POST https://harvest.greenhouse.io/v1/applications/{id}/unreject

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

URL parameters

ParameterDescription
idID of the application to unreject

JSON Body Parameters

No JSON body parameters

Approvals

An organization’s approvals

The approval flow object

{
  "id": 49394,
  "offer_id": 45545,
  "sequential": true,
  "version": 2,
  "approval_type": "offer_candidate",
  "approval_status": "pending",
  "job_id": 12321,
  "requested_by_user_id": 543,
  "approver_groups": [
    {
      "id": 2011242,
      "approvals_required": 1,
      "created_at": "2018-03-30T19:32:04.295Z",
      "resolved_at": null,
      "priority": 1,
      "job_id": 12321,
      "offer_id": null,
      "approvers": [
        {
          "id": 1234,
          "name": "Michael Clayton",
          "employee_id": "abc-123",
          "email_addresses": ["mclayton@example.com"]
        }
      ]
    },
    {
      "id": 2011241,
      "approvals_required": 1,
      "created_at": "2018-03-30T19:32:00.150Z",
      "resolved_at": "2018-03-30T19:34:17.374Z",
      "priority": 0,
      "job_id": 12321,
      "offer_id": null,
      "approvers": [
        {
          "id": 1235,
          "name": "Clay Michaels",
          "employee_id": "abc-124",
          "email_addresses": ["cmichaels@example.com"]
        }
      ]
    }
  ]
}

Noteworthy Attributes

AttributeDescription
idThe approval’s unique identifier
offer_idThe specific offer for this approval. This will be empty for job approvals.
sequentialtrue or false based on whether the groups in this flow must approve sequentially
versionThe specific version of this flow.
approval_typeone of ‘offer_job’, 'open_job’, or 'offer_candidate’
approval_statusone of 'pending’, 'approved’, or 'rejected’
job_idThe job for which approval is configured. This always has a value.
requested_by_user_idThe user who requested this approval be started.

GET: List Approvals For Job

curl 'https://harvest.greenhouse.io/v1/jobs/{job_id}/approval_flows'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
[
    {
        "id": 49394,
        "offer_id": 45545,
        "sequential": true,
        "version": 2,
        "approval_type": "offer_candidate",
        "approval_status": "pending",
        "job_id": 12321,
        "requested_by_user_id": 543,
        "approver_groups": [
            {
                "id": 2011242,
                "approvals_required": 1,
                "created_at": "2018-03-30T19:32:04.295Z",
                "resolved_at": null,
                "priority": 1,
                "job_id": 12321,
                "offer_id": null,
                "approvers": [
                  {
                    "id": 1234,
                    "name": "Michael Clayton",
                    "employee_id": "abc-123",
                    "email_addresses": ["mclayton@example.com"]
                  }
               ]
            },
            {
                "id": 2011241,
                "approvals_required": 1,
                "created_at": "2018-03-30T19:32:00.150Z",
                "resolved_at": "2018-03-30T19:34:17.374Z",
                "priority": 0,
                "job_id": 12321,
                "offer_id": null,
                "approvers": [
                  {
                    "id": 1235,
                    "name": "Clay Michaels",
                    "employee_id": "abc-124",
                    "email_addresses": ["cmichaels@example.com"]
                  }
               ]
            }
        ]
    },
    {
        "id": 49395,
        "offer_id": null,
        "sequential": true,
        "version": 1,
        "approval_type": "offer_job",
        "approval_status": "pending",
        "job_id": 12321,
        "requested_by_user_id": 545,
        "approver_groups": [
            {
                "id": 2011247,
                "approvals_required": 1,
                "created_at": "2018-03-30T19:32:04.295Z",
                "resolved_at": null,
                "priority": 1,
                "job_id": 12321,
                "offer_id": null,
                "approvers": [
                  {
                    "id": 1234,
                    "name": "Michael Clayton",
                    "employee_id": "abc-123",
                    "email_addresses": ["mclayton@example.com"]
                  }
               ]
            },
        ]
    }
]

List all of a job’s approval flows

HTTP Request

GET https://harvest.greenhouse.io/v1/jobs/{id}/approval_flows

Querystring parameters

ParameterDescription
idThe id of the job for which you’d like to see approvals


See noteworthy response attributes.

GET: Retrieve Approval Flow

curl 'https://harvest.greenhouse.io/v1/approval_flows/{id}'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
{
  "id": 49394,
  "offer_id": 45545,
  "sequential": true,
  "version": 2,
  "approval_type": "offer_candidate",
  "approval_status": "pending",
  "job_id": 12321,
  "requested_by_user_id": 543,
  "approver_groups": [
    {
      "id": 2011242,
      "approvals_required": 1,
      "created_at": "2018-03-30T19:32:04.295Z",
      "resolved_at": null,
      "priority": 1,
      "job_id": 12321,
      "offer_id": null,
      "approvers": [
        {
          "id": 1234,
          "name": "Michael Clayton",
          "employee_id": "abc-123",
          "email_addresses": ["mclayton@example.com"]
        }
      ]
    },
    {
      "id": 2011241,
      "approvals_required": 1,
      "created_at": "2018-03-30T19:32:00.150Z",
      "resolved_at": "2018-03-30T19:34:17.374Z",
      "priority": 0,
      "job_id": 12321,
      "offer_id": null,
      "approvers": [
        {
          "id": 1235,
          "name": "Clay Michaels",
          "employee_id": "abc-125",
          "email_addresses": ["cmichaels@example.com"]
        }
      ]
    }
  ]
}

HTTP Request

GET https://harvest.greenhouse.io/v1/approval_flows/{id}

URL Parameters

ParameterDescription
idThe ID of the approval flow to retrieve


See noteworthy response attributes.

POST: Request Approvals

curl -X POST 'https://harvest.greenhouse.io/v1/approval_flows/{id}/request_approvals'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

Given an approval flow, request it be started. This will change the state of the first approver group from “waiting” to “due” and mark the On-Behalf-Of user as the requesting user. This endpoint will fail with a 403 response if the On-Behalf-Of user can’t see the hiring plan or can’t request approvals. It will fail with a 422 response if the approval flow can’t be started.

HTTP Request

POST https://harvest.greenhouse.io/v1/approval_flows/{id}/request_approvals

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

GET: Pending Approvals For User

curl -X GET 'https://harvest.greenhouse.io/v1/users/{id}/pending_approvals'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns a JSON response, structured like this:

[
    {
        "id": 34564,
        "status": "waiting",
        "created_at": "2017-03-23T18:58:27.796Z",
        "resolved_at": null,
        "request_sent_at": "2017-03-23T18:58:27.796Z",
        "reminder_sent_at": "2017-03-25T18:58:27.796Z",
        "reminders_sent": 2,
        "approver_group_id": 3432,
        "reminder_sent_by_user_id": 343,
        "hiring_plan_id": 4567,
        "offer_id": null,
        "approval_flow_id": 292244,
        "approval_flow_type": "open_job",
        "approval_flow_status": "pending"

    },
    {
        "id": 34568,
        "status": "due",
        "created_at": "2017-04-23T18:58:27.796Z",
        "resolved_at": null,
        "request_sent_at": "2017-04-23T18:58:27.796Z",
        "reminder_sent_at": "2017-04-25T18:58:27.796Z",
        "reminders_sent": 1,
        "approver_group_id": 3436,
        "reminder_sent_by_user_id": 343,
        "hiring_plan_id": 4568,
        "offer_id": 4534,
        "approval_flow_id": 268182,
        "approval_flow_type": "offer_candidate",
        "approval_flow_status": "pending"
    }
]

Returns all pending approvals for this user. Pending approvals are defined as an approval chain that is not approved or rejected, that this user has not already approved or rejected, in a group that has not yet determined approval or rejection.

HTTP Request

GET https://harvest.greenhouse.io/v1/users/{user_id}/pending_approvals

URL Parameters

ParameterDescription
idThe ID of the user whose pending approvals we want.

Querystring Parameters

ParameterDescription
type'job’ or 'offer’, where 'offer’ returns only approvals which are for a specific offer and 'job’ specifically excludes approvals for specific offers. Leaving this blank will return all approvals.

Noteworthy Attributes

AttributeDescription
statusThis is either “waiting” or “due” for pending approvals
approver_group_idThis is Approver Group ID used in post requests to replace this user in approval steps.

PUT: Replace an approver in an approver group

curl -X PUT 'https://harvest.greenhouse.io/v1/approver_groups/{id}/replace_approvers'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "remove_user_id": 1443,
  "add_user_id": 5432
}

The above returns a JSON success message with the following information.

{
  "success": "true",
  "message": "Approver group updated.",
  "approval_flow_id": 454,
  "approver_group_id": 343,
  "removed_user_id": 1443,
  "added_user_id": 5432
}

Removes the approver with user id given in remove_user_id and adds a new approver with the user id in add_user_id. Only approvers in unresolved groups may be replaced with this endpoint. If a group is currently “due”, the new user will be notified that action is required.

HTTP Request

PUT https://harvest.greenhouse.io/v1/approver_groups/{approver_group_id}/replace_approvers

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes. Must have access to the approval flow.

URL Parameters

ParameterDescription
approver_group_idThe approver group in which we are replacing an approver.

Input JSON Parameters

ParameterDescription
remove_user_idThe user id of the approver to be removed.
add_user_idThe user id of the new approver. Must have access to this approval flow.

Noteworthy Output JSON Parameters

ParameterDescription
approval_flow_idThe approval flow that was changed.

PUT: Create or replace an approval flow

curl -X PUT 'https://harvest.greenhouse.io/v1/jobs/{job_id}/approval_flows'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
    "approval_type": "offer_candidate",
    "offer_id": 343,
    "sequential": false,
    "approver_groups": [
        {
            "approvals_required": 2,
            "approvers": [
                { "user_id": 1432 },
                { "email": "eddie.vedder@example.com" }
            ]
        },
        {
            "approvals_required": 1,
            "approvers": [
                { "employee_id": "abc-123" }
            ]
        }
    ]
}

The above returns a JSON success message with the following information.

{
    "success": true,
    "approval_flow_id": 49394,
}

Endpoint may create or replace the entirety of an approval flow on a certain job or offer. If no approval flow exists, it will create it. Otherwise, it will modify the existing one. The priority of the approver group is implied by the order of the approver_groups element, with the first receiving first priority. Approvers who already exist in the group with matching priority will remain unchanged, approvers who are not included will be removed, and new approvers will be added. If modifying an approval that has been started, this endpoint will restart it, which will remove previous approvals, and notify the first group that an approval is due. Approvals in the rejected or approved state can not be modified by this endpoint.

HTTP Request

PUT https://harvest.greenhouse.io/v1/jobs/{job_id}/approval_flows

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes. Must have access to the approval flow.

URL Parameters

ParameterDescription
job_idWe will replace the approval flow on this job.

Input JSON Parameters

ParameterDescription
approval_typeRequired. One of offer_job, open_job, or offer_candidate. Designates which of the approval flows to replace. This is used for look-up and will not be edited by the endpoint.
offer_idOptional. If included, it will search for an offer approval for this specific offer only. The job level approval will stay unchanged. If this is included, only 'offer_candidate’ is a valid approval type. This is used for look-up and will not be edited by the endpoint.
sequentialRequired. Accepts boolean true or false.
approver_groupsThe list of approver groups. The order of the approver group list implies the 'priority’ value in the approver group object, with the first listed group receiving the highest priority and so on.
approvals_requiredRequired. The number of approvals that must be given for this group to be considered approved and sent to the next group. Must be a number greater than zero.
approversMust contain the Greenhouse user_id, e-mail address, or employee_id for an active user in Greenhouse. The user must have access to the job. The number of users supplied must be greater than or equal to the approvals_required value for this group. If the approver appears in more than one group, he will be appear in the group with the highest priority and ignored in later groups.

Candidates

An organization’s candidates.

The candidate object

{
    "id": 53883394,
    "first_name": "John",
    "last_name": "Locke",
    "company": "The Tustin Box Company",
    "title": "Man of Mystery",
    "created_at": "2017-08-15T03:31:46.591Z",
    "updated_at": "2017-09-28T12:29:30.497Z",
    "last_activity": "2017-09-28T12:29:30.481Z",
    "is_private": false,
    "photo_url": "https://prod-heroku.s3.amazonaws.com/people/photos/053/883/394/original/corgi.jpg?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509193807&Signature=cg%2BhyNTvvNgTTzWtsMJJZvPRYH4%3D",
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/person_attachments/data/077/683/131/original/John_Locke_Offer_Packet_09_27_2017.pdf?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509193807&Signature=R5TbJPzD7TO5NgX8K8Y0yogPstY%3D",
            "type": "offer_packet"
        }
    ],
    "application_ids": [
        69102626,
        65153308
    ],
    "phone_numbers": [
        {
            "value": "555-555-5555",
            "type": "mobile"
        }
    ],
    "addresses": [
        {
            "value": "123 City Street\nNew York, Ny 10001",
            "type": "home"
        }
    ],
    "email_addresses": [
        {
            "value": "test@work.com",
            "type": "work"
        },
        {
            "value": "test@example.com",
            "type": "personal"
        }
    ],
    "website_addresses": [
        {
            "value": "mysite.com",
            "type": "personal"
        }
    ],
    "social_media_addresses": [
        {
            "value": "twitter.com/test"
        }
    ],
    "recruiter": {
        "id": 92120,
        "first_name": "Greenhouse",
        "last_name": "Admin",
        "name": "Greenhouse Admin",
        "employee_id": "67890"
        },
    "coordinator": {
        "id": 453636,
        "first_name": "Jane",
        "last_name": "Smith",
        "name": "Jane Smith",
        "employee_id": "12345"
    },
    "tags": [
        "Python",
        "Ruby"
    ],
    "applications": [
        {
            "id": 69102626,
            "candidate_id": 53883394,
            "prospect": false,
            "applied_at": "2017-09-27T12:03:02.728Z",
            "rejected_at": "2017-09-27T12:11:40.877Z",
            "last_activity_at": "2017-09-28T12:29:30.481Z",
            "location": {
                "address": "New York, New York, USA"
            },
            "source": {
                "id": 16,
                "public_name": "LinkedIn (Prospecting)"
            },
            "credited_to": {
                "id": 165372,
                "first_name": "Joel",
                "last_name": "Job Admin",
                "name": "Joel Job Admin",
                "employee_id": null
            },
            "rejection_reason": {
                "id": 9504,
                "name": "Hired another candidate",
                "type": {
                    "id": 1,
                    "name": "We rejected them"
                }
            },
            "rejection_details": {
                "custom_fields": {
                    "custom_rejection_question_field": null
                },
                "keyed_custom_fields": {
                    "custom_rejection_question_field": {
                        "name": "Custom Rejection Question Field",
                        "type": "short_text",
                        "value": null
                    }
                }
            },
            "jobs": [
                {
                    "id": 149995,
                    "name": "DevOps Engineer"
                }
            ],
            "status": "rejected",
            "current_stage": {
                "id": 1073533,
                "name": "Take Home Test"
            },
            "answers": [
                {
                    "question": "How did you hear about this job?",
                    "answer": "A friend"
                },
                {
                    "question": "Website",
                    "answer": "https://example.com"
                },
                {
                    "question": "LinkedIn Profile",
                    "answer": "https://linkedin.com/example"
                }
            ],
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            }
        },
        {
            "id": 65153308,
            "candidate_id": 53883394,
            "prospect": false,
            "applied_at": "2017-08-15T03:31:46.637Z",
            "rejected_at": null,
            "last_activity_at": "2017-09-28T12:29:30.481Z",
            "location": {
                "address": "New York, New York, United States"
            },
            "source": {
                "id": 12,
                "public_name": "Meetups"
            },
            "credited_to": {
                "id": 566819,
                "first_name": "Bob",
                "last_name": "Smith",
                "name": "Bob Smith",
                "employee_id": null
            },
            "rejection_reason": null,
            "rejection_details": null,
            "jobs": [
                {
                    "id": 299100,
                    "name": "Data Scientist - BK"
                }
            ],
            "status": "active",
            "current_stage": {
                "id": 2966800,
                "name": "Face to Face"
            },
            "answers": [],
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            }
        }
    ],
    "educations": [
        {
            "id": 561227,
            "school_name": "University of Michigan - Ann Arbor",
            "degree": "Bachelor's Degree",
            "discipline": "Computer Science",
            "start_date": "2012-08-15T00:00:00.000Z",
            "end_date": "2016-05-15T00:00:00.000Z"
        }
    ],
    "employments": [
        {
            "id": 8485064,
            "company_name": "Greenhouse",
            "title": "Engineer",
            "start_date": "2012-08-15T00:00:00.000Z",
            "end_date": "2016-05-15T00:00:00.000Z"
        }
    ],
    "custom_fields": {
        "desired_salary": "1000000000",
        "work_remotely": true,
        "graduation_year": "2018"
    },
    "keyed_custom_fields": {
        "desired_salary": {
            "name": "Desired Salary",
            "type": "short_text",
            "value": "1000000000"
        },
        "work_remotely": {
            "name": "Work Remotely",
            "type": "boolean",
            "value": true
        },
        "graduation_year_1": {
            "name": "Graduation Year",
            "type": "single_select",
            "value": "2018"
        }
    }
}

Noteworthy attributes

AttributeDescription
idThe candidate’s unique identifier
companyThe company at which the candidate currently works
titleThe candidate’s current title
is_privateWhether the candidate is private or not. One of: [“true”, “false”]
application_idsArray of application IDs associated with this candidate. Can contain none, one, or several application IDs.
phone_numbers[].typeOne of: [“home”, “work”, “mobile”, “skype”, “other”]
addresses[].typeOne of: [“home”, “work”, “other”]
email_addresses[].typeOne of: [“personal”, “work”, “other”]
website_addresses[].typeOne of: [“personal”, “company”, “portfolio”, “blog”, “other”]
recruiterThe recruiter user who is responsible for this candidate.
coordinatorThe coordinator user who is responsible for this candidate.
attachments[].typeOne of: [“resume”, “cover_letter”, “admin_only”, “public”, “offer_packet”, “offer_letter”, “take_home_test”, “other”]
attachments[].urlURLs expire in 30 days.
custom_fieldsContains a hash of the custom fields configured for this resource. The properties in this hash reflect the active custom fields as of the time this method is called.
keyed_custom_fieldsThis contains the same information as custom_fields but formatted in a different way that includes more information. This will tell you the type of custom field data to expect, the text name of custom field, and the value. The key of this hash is the custom field’s immutable field key, which will not change even if the name of the custom field is changed in Greenhouse.

GET: List Candidates

curl 'https://harvest.greenhouse.io/v1/candidates'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
 {
    "id": 53883394,
    "first_name": "John",
    "last_name": "Locke",
    "company": "The Tustin Box Company",
    "title": "Man of Mystery",
    "created_at": "2017-08-15T03:31:46.591Z",
    "updated_at": "2017-09-28T12:29:30.497Z",
    "last_activity": "2017-09-28T12:29:30.481Z",
    "is_private": false,
    "photo_url": "https://prod-heroku.s3.amazonaws.com/people/photos/053/883/394/original/corgi.jpg?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509193807&Signature=cg%2BhyNTvvNgTTzWtsMJJZvPRYH4%3D",
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/person_attachments/data/077/683/131/original/John_Locke_Offer_Packet_09_27_2017.pdf?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509193807&Signature=R5TbJPzD7TO5NgX8K8Y0yogPstY%3D",
            "type": "offer_packet"
        }
    ],
    "application_ids": [
        69103370,
        65153308
    ],
    "phone_numbers": [
        {
            "value": "555-555-5555",
            "type": "mobile"
        }
    ],
    "addresses": [
        {
            "value": "123 City Street\nNew York, Ny 10001",
            "type": "home"
        }
    ],
    "email_addresses": [
        {
            "value": "test@work.com",
            "type": "work"
        }
    ],
    "website_addresses": [
        {
            "value": "mysite.com",
            "type": "personal"
        }
    ],
   "social_media_addresses": [],
    "recruiter": {
        "id": 92120,
        "first_name": "Greenhouse",
        "last_name": "Admin",
        "name": "Greenhouse Admin",
        "employee_id": null
    },
    "coordinator": null,
    "tags": [
        "Python",
        "Ruby"
    ],
    "applications": [
        {
            "id": 69103370,
            "candidate_id": 53883394,
            "prospect": true,
            "applied_at": "2017-09-27T12:21:37.234Z",
            "rejected_at": null,
            "last_activity_at": "2017-09-28T12:29:30.481Z",
            "location": {
                "address": "New York, New York, USA"
            },
            "source": {
                "id": 16,
                "public_name": "LinkedIn (Prospecting)"
            },
            "credited_to": {
                "id": 92120,
                "first_name": "Greenhouse",
                "last_name": "Admin",
                "name": "Greenhouse Admin",
                "employee_id": null
            },
            "rejection_reason": null,
            "rejection_details": null,
            "jobs": [
                {
                    "id": 87752,
                    "name": "Full Stack Engineer"
                }
            ],
            "status": "active",
            "current_stage": null,
            "answers": [],
            "prospect_detail": {
                "prospect_pool": {
                    "id": 224,
                    "name": "Cold Outreach: Sourced"
                },
                "prospect_stage": {
                    "id": 817,
                    "name": "Contacted"
                },
                "prospect_owner": {
                    "id": 92120,
                    "name": "Greenhouse Admin"
                }
            }
        },
        {
            "id": 65153308,
            "candidate_id": 53883394,
            "prospect": false,
            "applied_at": "2017-08-15T03:31:46.637Z",
            "rejected_at": null,
            "last_activity_at": "2017-09-28T12:29:30.481Z",
            "location": null,
            "source": {
                "id": 12,
                "public_name": "Meetups"
            },
            "credited_to": {
                "id": 566819,
                "first_name": "Bob",
                "last_name": "Smith",
                "name": "Bob Smith",
                "employee_id": null
            },
            "rejection_reason": null,
            "rejection_details": null,
            "jobs": [
                {
                    "id": 299100,
                    "name": "Data Scientist - BK"
                }
            ],
            "status": "active",
            "current_stage": {
                "id": 2966800,
                "name": "Face to Face"
            },
            "answers": [],
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            }
        }
    ],
    "educations": [
        {
            "id": 561227,
            "school_name": "University of Michigan - Ann Arbor",
            "degree": "Bachelor's Degree",
            "discipline": "Computer Science",
            "start_date": "2012-08-15T00:00:00.000Z",
            "end_date": "2016-05-15T00:00:00.000Z"
        }
    ],
    "employments": [
        {
            "id": 8485064,
            "company_name": "Greenhouse",
            "title": "Engineer",
            "start_date": "2012-08-15T00:00:00.000Z",
            "end_date": "2016-05-15T00:00:00.000Z"
        }
    ],
    "custom_fields": {
        "desired_salary": "1000000000",
        "work_remotely": true,
        "graduation_year": "2018"
    },
    "keyed_custom_fields": {
        "desired_salary": {
            "name": "Desired Salary",
            "type": "short_text",
            "value": "1000000000"
        },
        "work_remotely": {
            "name": "Work Remotely",
            "type": "boolean",
            "value": true
        },
        "graduation_year_1": {
            "name": "Graduation Year",
            "type": "single_select",
            "value": "2018"
        }
     }
  }
]

List all of an organization’s candidates.

HTTP Request

GET https://harvest.greenhouse.io/v1/candidates

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
created_beforeReturn only candidates that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_afterReturn only candidates that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_beforeReturn only candidates that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_afterReturn only candidates that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.
job_idIf supplied, only return candidates that have applied to this job. Will return both when a candidate has applied to a job and when they’re a prospect for a job.
emailIf supplied, only return candidates who have a matching e-mail address. If supplied with job_id, only return a candidate with a matching e-mail with an application on the job. If email and candidate_ids are included, candidate_ids will be ignored.
candidate_idsIf supplied, return only the candidates with the given ids. These are supplied as a comma separated string. e.g.: “candidate_ids=123,456,789”. When combined with job_id, only return candidates with an application on the job. A maximum of 50 candidates can be returned this way.


See noteworthy response attributes.

GET: Retrieve Candidate

curl 'https://harvest.greenhouse.io/v1/candidates/{id}'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

{
    "id": 53883394,
    "first_name": "John",
    "last_name": "Locke",
    "company": "The Tustin Box Company",
    "title": "Man of Mystery",
    "created_at": "2017-08-15T03:31:46.591Z",
    "updated_at": "2017-09-28T12:29:30.497Z",
    "last_activity": "2017-09-28T12:29:30.481Z",
    "is_private": false,
    "photo_url": "https://prod-heroku.s3.amazonaws.com/people/photos/053/883/394/original/corgi.jpg?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509193807&Signature=cg%2BhyNTvvNgTTzWtsMJJZvPRYH4%3D",
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/person_attachments/data/077/683/131/original/John_Locke_Offer_Packet_09_27_2017.pdf?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509193807&Signature=R5TbJPzD7TO5NgX8K8Y0yogPstY%3D",
            "type": "offer_packet"
        }
    ],
    "application_ids": [
        69102626,
        65153308
    ],
    "phone_numbers": [
        {
            "value": "555-555-5555",
            "type": "mobile"
        }
    ],
    "addresses": [
        {
            "value": "123 City Street\nNew York, Ny 10001",
            "type": "home"
        }
    ],
    "email_addresses": [
        {
            "value": "test@work.com",
            "type": "work"
        },
        {
            "value": "test@example.com",
            "type": "personal"
        }
    ],
    "website_addresses": [
        {
            "value": "mysite.com",
            "type": "personal"
        }
    ],
    "social_media_addresses": [
        {
            "value": "twitter.com/test"
        }
    ],
    "recruiter": {
        "id": 92120,
        "first_name": "Greenhouse",
        "last_name": "Admin",
        "name": "Greenhouse Admin",
        "employee_id": "67890"
        },
    "coordinator": {
        "id": 453636,
        "first_name": "Jane",
        "last_name": "Smith",
        "name": "Jane Smith",
        "employee_id": "12345"
    },
    "tags": [
        "Python",
        "Ruby"
    ],
    "applications": [
        {
            "id": 69102626,
            "candidate_id": 53883394,
            "prospect": false,
            "applied_at": "2017-09-27T12:03:02.728Z",
            "rejected_at": "2017-09-27T12:11:40.877Z",
            "last_activity_at": "2017-09-28T12:29:30.481Z",
            "location": {
                "address": "New York, New York, USA"
            },
            "source": {
                "id": 16,
                "public_name": "LinkedIn (Prospecting)"
            },
            "credited_to": {
                "id": 165372,
                "first_name": "Joel",
                "last_name": "Job Admin",
                "name": "Joel Job Admin",
                "employee_id": null
            },
            "rejection_reason": {
                "id": 9504,
                "name": "Hired another candidate",
                "type": {
                    "id": 1,
                    "name": "We rejected them"
                }
            },
            "rejection_details": {
                "custom_fields": {
                    "custom_rejection_question_field": null
                },
                "keyed_custom_fields": {
                    "custom_rejection_question_field": {
                        "name": "Custom Rejection Question Field",
                        "type": "short_text",
                        "value": null
                    }
                }
            },
            "jobs": [
                {
                    "id": 149995,
                    "name": "DevOps Engineer"
                }
            ],
            "status": "rejected",
            "current_stage": {
                "id": 1073533,
                "name": "Take Home Test"
            },
            "answers": [
                {
                    "question": "How did you hear about this job?",
                    "answer": "A friend"
                },
                {
                    "question": "Website",
                    "answer": "https://example.com"
                },
                {
                    "question": "LinkedIn Profile",
                    "answer": "https://linkedin.com/example"
                }
            ],
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            }
        },
        {
            "id": 65153308,
            "candidate_id": 53883394,
            "prospect": false,
            "applied_at": "2017-08-15T03:31:46.637Z",
            "rejected_at": null,
            "last_activity_at": "2017-09-28T12:29:30.481Z",
            "location": {
                "address": "New York, New York, United States"
            },
            "source": {
                "id": 12,
                "public_name": "Meetups"
            },
            "credited_to": {
                "id": 566819,
                "first_name": "Bob",
                "last_name": "Smith",
                "name": "Bob Smith",
                "employee_id": null
            },
            "rejection_reason": null,
            "rejection_details": null,
            "jobs": [
                {
                    "id": 299100,
                    "name": "Data Scientist - BK"
                }
            ],
            "status": "active",
            "current_stage": {
                "id": 2966800,
                "name": "Face to Face"
            },
            "answers": [],
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            }
        }
    ],
    "educations": [
        {
            "id": 561227,
            "school_name": "University of Michigan - Ann Arbor",
            "degree": "Bachelor's Degree",
            "discipline": "Computer Science",
            "start_date": "2012-08-15T00:00:00.000Z",
            "end_date": "2016-05-15T00:00:00.000Z"
        }
    ],
    "employments": [
        {
            "id": 8485064,
            "company_name": "Greenhouse",
            "title": "Engineer",
            "start_date": "2012-08-15T00:00:00.000Z",
            "end_date": "2016-05-15T00:00:00.000Z"
        }
    ],
    "custom_fields": {
        "desired_salary": "1000000000",
        "work_remotely": true,
        "graduation_year": "2018"
    },
    "keyed_custom_fields": {
        "desired_salary": {
            "name": "Desired Salary",
            "type": "short_text",
            "value": "1000000000"
        },
        "work_remotely": {
            "name": "Work Remotely",
            "type": "boolean",
            "value": true
        },
        "graduation_year_1": {
            "name": "Graduation Year",
            "type": "single_select",
            "value": "2018"
        }
    }
}

Retrieve a candidate by its id.

HTTP Request

GET https://harvest.greenhouse.io/v1/candidates/{id}

URL Parameters

ParameterDescription
idThe ID of the candidate to retrieve


See noteworthy response attributes.

DELETE: Delete Candidate

curl -X DELETE 'https://harvest.greenhouse.io/v1/candidates/{id}'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above returns a JSON response, structured like this:

{
  "message": "Person 29622362 has been deleted."
}

Delete a candidate by id.

HTTP Request

DELETE https://harvest.greenhouse.io/v1/candidates/{id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

PATCH: Edit Candidate

curl -X PATCH 'https://harvest.greenhouse.io/v1/candidates/{id}'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "first_name": "New",
  "last_name": "Name",
  "company": "The Tustin Box Company",
  "title": "Man of Mystery",
  "is_private": true,
  "phone_numbers": [
    {
      "value": "555-1212",
      "type": "mobile"
    }
  ],
  "addresses": [
    {
      "value": "123 Fake St.",
      "type": "home"
    }
  ],
  "email_addresses": [
    {
      "value": "john.locke+work@example.com",
      "type": "work"
    },
    {
      "value": "john.locke@example.com",
      "type": "personal"
    }
  ],
  "website_addresses": [
    {
      "value": "johnlocke.example.com",
      "type": "personal"
    }
  ],
  "social_media_addresses": [
    {
      "value": "linkedin.example.com/john.locke"
    },
    {
      "value": "@johnlocke"
    }
  ],
  "recruiter": { "user_id": 4354 },
  "coordinator": { "email": "coordinator@example.com" },
  "tags": [
    "Walkabout",
    "Orientation"
  ],
  "custom_fields": [
    {
        "id": 1234,
        "value": "Some new value"
    },
    {
        "name_key": "single_select_field_name",
        "value": 12345
   },
   {
        "id": 5678,
        "delete_value": "true"
   }
  ]
}

The above returns a JSON response, structured like this:

[
  {
      "id": 53883394,
      "first_name": "New",
      "last_name": "Name",
      "company": "The Tustin Box Company",
      "title": "Man of Mystery",
      "created_at": "2017-08-15T03:31:46.591Z",
      "updated_at": "2017-09-28T12:54:34.257Z",
      "last_activity": "2017-09-28T12:54:34.243Z",
      "is_private": true,
      "photo_url": "https://prod-heroku.s3.amazonaws.com/people/photos/053/883/394/original/corgi.jpg?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509195274&Signature=NHilozZgXPHOI9uvpKTnf3A50Gc%3D",
      "attachments": [
          {
              "filename": "John_Locke_Offer_Packet_09_28_2017.pdf",
              "url": "https://prod-heroku.s3.amazonaws.com/person_attachments/data/077/815/020/original/John_Locke_Offer_Packet_09_28_2017.pdf?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509195274&Signature=Vb7z8GlHJXvwqhvx%2BTrIZ32zaVo%3D",
              "type": "offer_packet"
          }
      ],
      "application_ids": [
          65153308
      ],
      "phone_numbers": [
          {
              "value": "555-1212",
              "type": "mobile"
          }
      ],
      "addresses": [
          {
              "value": "123 Fake Street",
              "type": "home"
          }
      ],
      "email_addresses": [
          {
              "value": "john.locke+work@example.com",
              "type": "work"
          },
          {
              "value": "john.locke@example.com",
              "type": "personal"
          }
      ],
      "website_addresses": [
          {
              "value": "johnlocke.example.com",
              "type": "personal"
          }
      ],
       "social_media_addresses": [
          {
            "value": "linkedin.example.com/john.locke"
          },
          {
            "value": "@johnlocke"
          }
      ],
      "recruiter": {
          "id": 92120,
          "first_name": "Greenhouse",
          "last_name": "Admin",
          "name": "Greenhouse Admin",
          "employee_id": null
      },
      "coordinator": null,
      "tags": [
          "Walkabout",
          "Orientation"
      ],
      "applications": [
          {
              "id": 65153308,
              "candidate_id": 53883394,
              "prospect": false,
              "applied_at": "2017-08-15T03:31:46.637Z",
              "rejected_at": null,
              "last_activity_at": "2017-09-28T12:54:34.243Z",
              "location": {
                  "address": "New York, New York, USA"
              },
              "source": {
                  "id": 12,
                  "public_name": "Meetups"
              },
              "credited_to": {
                  "id": 566819,
                  "first_name": "Bob",
                  "last_name": "Smith",
                  "name": "Bob Smith",
                  "employee_id": "ABC12345"
              },
              "rejection_reason": null,
              "rejection_details": null,
              "jobs": [
                  {
                      "id": 299100,
                      "name": "Data Scientist - BK"
                  }
              ],
              "status": "active",
              "current_stage": {
                  "id": 2966800,
                  "name": "Face to Face"
              },
              "answers": [],
              "prospect_detail": {
                  "prospect_pool": null,
                  "prospect_stage": null,
                  "prospect_owner": null
              }
          }
      ],
      "educations": [],
      "employments": [],
      "custom_fields": {
        "current_salary": "$23k",
        "desired_salary": "$42k"
      },
      "keyed_custom_fields": {
        "current_salary": {
          "name": "Current salary",
          "type": "short_text",
          "value": "$23k"
        },
        "desired_salary": {
          "name": "Desired salary",
          "type": "short_text",
          "value": "$42k"
        }
     }
  }     
]

Update or patch a single candidate by its id.

HTTP Request

PATCH https://harvest.greenhouse.io/v1/candidates/{id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
first_nameNostringThe candidate’s first name
last_nameNostringThe candidate’s last name
companyNostringThe candidate’s company
titleNostringThe candidate’s title
is_privateWhether the candidate is private or not. One of: [“true”, “false”]
phone_numbers[]Nophone_numberArray of phone numbers. Passing an empty array will clear all.
addresses[]NoaddressArray of addresses. Passing an empty array will clear all.
email_addresses[]Noemail_addressArray of email addresses. Passing an empty array will clear all.
website_addresses[]Nowebsite_addressArray of website addresses. Passing an empty array will clear all.
social_media_addresses[]Nosocial_media_addressArray of social media addresses. Passing an empty array will clear all.
tags[]NostringArray of tags as strings. Passing an empty array will clear all.
custom_fields[]Nocustom_fieldArray of hashes containing new custom field values. Passing an empty array does nothing.
recruiterNoHashAn object representing the candidate’s new recruiter
recruiter[id]NoIntegerThe ID of the new recruiter - either id or email must be present.
recruiter[email]NoStringThe email of the new recruiter - either id or email must be present.
coordinatorNoHashAn object representing the candidate’s new coordinator
coordinator[id]NoIntegerThe ID of the new coordinator - either id or email must be present.
coordinator[email]NoStringThe email of the new coordinator - either id or email must be present.

Custom Field Parameters

The custom field parameter structure is different in the PATCH method then in GET methods and responses. Certain type of custom fields require different elements to be included, while deleting a field requires a specific argument. What follows is the description of each item in a custom field element and what is required depending on the type.

ParameterRequired forDescription
idallThe custom field id for this particular custom field. One of this or name_key is required.
name_keyallThe field key for this custom field. This can be found in Greenhouse while editing custom options as “Immutable Field Key” This or id is required for all custom field elements.
valueallThe value field contains the new custom field value. In most cases this will be a string or a number. In the case of single-select or multi-select custom fields, this will be a custom field option id or an array of custom field option ids, respectively. In the case of single-select fields, this can also be a string that matches an existing option value name exactly.
unitcurrencyThis contains the currency unit for a currency custom field. It is only required when updating a currency custom field. This should accept any 3-character currency code from the ISO-4217 standard.
delete_valuen/aWhen this element is included with a value of “true” (note, string true, not boolean true) the custom field value will be removed from Greenhouse. Note that updating a custom field value to nil or a blank string will not work, as validations require these to be non-blank values.


See noteworthy response attributes.

POST: Add Attachment

curl -X POST 'https://harvest.greenhouse.io/v1/candidates/{id}/attachments'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "filename" : "resume.pdf",
  "type" : "resume",
  "content" : "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs...",
  "content_type" : "application/pdf"
}

The above command returns a JSON response, structured like this:

{
  "filename": "resume.pdf",
  "url": "https://prod-heroku.s3.amazonaws.com/...",
  "type": "resume",
  "content_type": "application/pdf"
}

Post an attachment to a candidate’s profile by the candidate id.

HTTP Request

POST https://harvest.greenhouse.io/v1/candidates/{id}/attachments

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
filenameYesstringName of the file
typeYesstringOne of: [“resume”, “cover_letter”, “admin_only”]
contentNostringBase64 encoded content of the attachment (if you are providing content, you do not need to provide url). String must be UTF-8 encoded.
urlNostringUrl of the attachment (if you are providing the url, you do not need to provide the content)
content_typeNo*stringThe content-type of the document you are sending. When using a URL, this generally isn’t needed, as the responding server will deliver a content type. This should be included for encoded content. Accepted content types are:
  • “application/atom+xml”
  • “application/javascript”
  • “application/json”
  • “application/msgpack”
  • “application/msword”
  • “application/pdf”
  • “application/rss+xml”
  • “application/vnd.ms-excel”
  • “application/vnd.openxmlformats-
    officedocument.spreadsheetml.sheet”
  • “application/vnd.openxmlformats-
    officedocument.wordprocessingml.document”
  • “application/vnd.ms-powerpoint”
  • “application/xml”
  • “application/x-www-form-urlencoded”
  • “application/x-yaml”
  • “application/zip”
  • “multipart/form-data”
  • “image/bmp”
  • “image/gif”
  • “image/jpeg”
  • “image/png”
  • “image/tiff”
  • “text/calendar”
  • “text/css”
  • “text/csv”
  • “text/html”
  • “text/javascript”
  • “text/plain”
  • “text/vcard”
  • “video/mpeg”

* - content_type is not required for purposes of backward compatibility. It is strongly recommended that you always include content type for document uploads.

POST: Add Candidate

curl -X POST 'https://harvest.greenhouse.io/v1/candidates'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "first_name": "John",
  "last_name": "Locke",
  "company": "The Tustin Box Company",
  "title": "Man of Mystery",
  "is_private": false,
  "phone_numbers": [
    {
      "value": "555-1212",
      "type": "mobile"
    }
  ],
  "addresses": [
    {
      "value": "123 Fake St.",
      "type": "home"
    }
  ],
  "email_addresses": [
    {
      "value": "john.locke+work@example.com",
      "type": "work"
    },
    {
      "value": "john.locke@example.com",
      "type": "personal"
    }
  ],
  "website_addresses": [
    {
      "value": "johnlocke.example.com",
      "type": "personal"
    }
  ],
  "social_media_addresses": [
    {
      "value": "linkedin.example.com/john.locke"
    },
    {
      "value": "@johnlocke"
    }
  ],
  "educations": [
    {
      "school_id": 459,
      "discipline_id": 940,
      "degree_id": 1230,
      "start_date": "2001-09-15T00:00:00.000Z",
      "end_date": "2004-05-15T00:00:00.000Z"
    }
  ],
  "employments": [
      {
          "company_name": "Greenhouse",
          "title": "Engineer",
          "start_date": "2012-08-15T00:00:00.000Z",
          "end_date": "2016-05-15T00:00:00.000Z"
      }
  ],
  "tags": [
    "Walkabout",
    "Orientation"
  ],
  "applications": [
    {
      "job_id": 215725
    },
     {
      "job_id": 185289
    }
  ]
}

The above returns a JSON response, structured like this:

{
    "id": 57683957,
    "first_name": "John",
    "last_name": "Locke",
    "company": "The Tustin Box Company",
    "title": "Man of Mystery",
    "created_at": "2017-09-28T13:27:54.735Z",
    "updated_at": "2017-09-28T13:27:55.229Z",
    "last_activity": "2017-09-28T13:27:55.213Z",
    "is_private": false,
    "photo_url": null,
    "attachments": [],
    "application_ids": [
        69201605,
        69201604
    ],
    "phone_numbers": [
        {
            "value": "555-1212",
            "type": "mobile"
        }
    ],
    "addresses": [
        {
            "value": "123 Fake St.",
            "type": "home"
        }
    ],
    "email_addresses": [
        {
            "value": "john.locke@example.com",
            "type": "personal"
        },
        {
            "value": "john.locke+work@example.com",
            "type": "work"
        }
    ],
    "website_addresses": [
        {
            "value": "johnlocke.example.com",
            "type": "personal"
        }
    ],
    "social_media_addresses": [
        {
            "value": "@johnlocke"
        },
        {
            "value": "linkedin.example.com/john.locke"
        }
    ],
    "recruiter": null,
    "coordinator": null,
    "tags": [
        "Orientation",
        "Walkabout"
    ],
    "applications": [
        {
            "id": 69201605,
            "candidate_id": 57683957,
            "prospect": false,
            "applied_at": "2017-09-28T13:27:54.873Z",
            "rejected_at": null,
            "last_activity_at": "2017-09-28T13:27:55.213Z",
            "location": {
                "address": "New York, New York, USA"
            },
            "source": null,
            "credited_to": null,
            "rejection_reason": null,
            "rejection_details": null,
            "jobs": [
                {
                    "id": 185289,
                    "name": "Product Specialist"
                }
            ],
            "status": "active",
            "current_stage": {
                "id": 1355395,
                "name": "Application Review"
            },
            "answers": [],
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            }
        },
        {
            "id": 69201604,
            "candidate_id": 57683957,
            "prospect": false,
            "applied_at": "2017-09-28T13:27:54.812Z",
            "rejected_at": null,
            "last_activity_at": "2017-09-28T13:27:55.213Z",
            "location": null,
            "source": null,
            "credited_to": null,
            "rejection_reason": null,
            "rejection_details": null,
            "jobs": [
                {
                    "id": 215725,
                    "name": "Operations Manger "
                }
            ],
            "status": "active",
            "current_stage": {
                "id": 1579673,
                "name": "Application Review"
            },
            "answers": [],
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            }
        }
    ],
    "educations": [
        {
            "id": 561226,
            "school_name": "Siena College",
            "discipline": "Computer Science",
            "degree": "Bachelor's Degree"
        }
    ],
    "employments": [
        {
            "id": 8485064,
            "company_name": "Greenhouse",
            "title": "Engineer",
            "start_date": "2012-08-15T00:00:00.000Z",
            "end_date": "2016-05-15T00:00:00.000Z"
        }
    ],
    "custom_fields": {
        "desired_salary": null,
        "work_remotely": null,
        "graduation_year": null
    },
    "keyed_custom_fields": {
        "desired_salary": null,
        "work_remotely": null,
        "graduation_year_1": null
    }
}

Create a new candidate.

HTTP Request

POST https://harvest.greenhouse.io/v1/candidates

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
first_nameYesstringThe candidate’s first name
last_nameYesstringThe candidate’s last name
companyNostringThe candidate’s company
titleNostringThe candidate’s title
phone_numbers[]Nophone_numberArray of phone numbers. Passing an empty array will clear all.
addresses[]NoaddressArray of addresses. Passing an empty array will clear all.
email_addresses[]Noemail_addressArray of email addresses. Passing an empty array will clear all.
website_addresses[]Nowebsite_addressArray of website addresses. Passing an empty array will clear all.
social_media_addresses[]Nosocial_media_addressArray of social media addresses. Passing an empty array will clear all.
tags[]NostringArray of tags as strings. Passing an empty array will clear all.
custom_fields[]Nocustom_fieldArray of hashes containing new custom field values. Passing an empty array does nothing.
recruiterNoObjectAn object representing the candidate’s recruiter
recruiter[id]NoIntegerThe ID of the recruiter - either id or email must be present.
recruiter[email]NoStringThe email of the recruiter - either id or email must be present.
coordinatorNoObjectAn object representing the candidate’s coordinator
coordinator[id]NoIntegerThe ID of the coordinator - either id or email must be present.
coordinator[email]NoStringThe email of the coordinator - either id or email must be present.
custom_fieldsNoArrayArray of custom field value objects - See “Custom Field Parameters” under Edit candidate for parameters.
activity_feed_notesNoArrayAn array of activity feed objects. See Add Note for parameters.
applicationsYesArrayAn array of application objects. At least one required. See Add Application for parameters.

See noteworthy response attributes.

POST: Add Candidate Application

curl -X POST 'https://harvest.greenhouse.io/v1/candidates/{id}/applications'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "job_id": 266926,
  "source_id": 7,
  "initial_stage_id": 2708728,
  "referrer": {
    "type": "id",
    "value": 770
  },
  "attachments": [{
    "filename": "resume.pdf",
    "type": "resume",
    "content": "MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6...",
    "content_type": "application/pdf"
}

The above command returns a JSON response, structured like this:

{
  "id": 38776620,
  "candidate_id": 15803530,
  "prospect": false,
  "applied_at": "2016-11-08T19:50:49.746Z",
  "rejected_at": null,
  "last_activity_at": "2016-11-04T19:46:40.377Z",
  "source": {
    "id": 7,
    "public_name": "Indeed"
  },
  "credited_to": {
        "id": 770,
        "first_name": "Moon",
        "last_name": "Colorado",
        "name": "Moon Colorado",
        "employee_id": null
    },
  "rejection_reason": null,
  "rejection_details": null,
  "jobs": [
    {
      "id": 266926,
      "name": "Construction Project Manager"
    }
  ],
  "status": "active",
  "current_stage": {
    "id": 1945557,
    "name": "Application Review"
  },
  "answers": [],
  "custom_fields": {
    "birthday": "1992-01-27",
    "bio": "This is my bio"
  },
  "prospect_detail": {
    "prospect_pool": null,
    "prospect_stage": null,
    "prospect_owner": null
  }
}

Create a new application for this candidate or prospect. If a prospect, this will add a new candidate application to the given job on their profile, this will not convert their existing prospect application into a candidate application.

HTTP Request

POST https://harvest.greenhouse.io/v1/candidates/{id}/applications

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
job_idYesintegerThe ID of the job you want to create an application to for this candidate
source_idNointegerThe id of the source to be credited for this application
initial_stage_idNointegerThe ID of the job stage this application will be created in.
referrerNoobjectAn object representing the referrer
referrer[type]NostringA string representing the type of referrer: ‘id’, 'email’, or 'outside’
referrer[value]NostringThe id of the user who made the referral (not the referrer id)
attachmentsNoarrayAn array of attachments to be uploaded to this application. See Add Attachment for parameters.

POST: Add Note

curl -X POST 'https://harvest.greenhouse.io/v1/candidates/{id}/activity_feed/notes'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "user_id": "158108",
  "body": "John Locke was moved into Recruiter Phone Screen for Accounting Manager on 03/27/2014 by Boone Carlyle",
  "visibility": "admin_only"
}

The above command returns a JSON response, structured like this:

{
  "id": 226809052,
  "created_at": "2015-07-17T16:29:31Z",
  "body": "John Locke was moved into Recruiter Phone Screen for Accounting Manager on 03/27/2014 by Boone Carlyle",
  "user": {
     "id": 214,
        "first_name": "Boone",
        "last_name": "Carlyle",
        "name": "Boone Carlyle",
        "employee_id": null
  },
  "private": false,
  "visiblity": "admin_only",
  "visibility": "admin_only"
}

Create a candidate note.

HTTP Request

POST https://harvest.greenhouse.io/v1/candidates/{id}/activity_feed/notes

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
user_idYesintegerThe ID of the user creating the note
bodyYesstringNote body
visibility*YesstringOne of: "admin_only", "private", "public"

* - Due to a legacy typo, the response includes the same value as visiblity. It is safe to ignore this value, but it is maintained for backward compatibility.

POST: Add E-mail Note

curl -X POST 'https://harvest.greenhouse.io/v1/candidates/{id}/activity_feed/emails'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "user_id": "214",
  "to": "candidate@example.com",
  "from": "recruiter@example.com",
  "cc": ["manager@example.com"],
  "subject": "Interview Scheduled",
  "body": "An interview has been scheduled for tomorrow."
}

The above command returns a JSON response, structured like this:

{
  "id": 226809053,
  "created_at": "2015-07-17T16:29:31Z",
  "subject": "Interview Scheduled",
  "body": "An interview has been scheduled for tomorrow.",
  "to": "candidate@example.com",
  "from": "recruiter@example.com",
  "cc": [
    "manager@example.com"
    ],
  "user": {
    "id": 214,
    "first_name": "Donald",
    "last_name": "Johnson",
    "name": "Donald Johnson",
    "employee_id": "12345"
  }
}

Create a candidate e-mail note.

HTTP Request

POST https://harvest.greenhouse.io/v1/candidates/{id}/activity_feed/emails

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
user_idYesintegerThe ID of the user creating the note
toYesstringThis is a free text field that is meant to be an e-mail address. E-mail format will not be validated.
fromYesstringThis is a free text field that is meant to be an e-mail address. E-mail format will not be validated.
ccNoArrayThis is meant to be an array of e-mail addresses. E-mail format will not be validated.
subjectYesstringThe subject line of the e-mail.
bodyYesstringThe body of the e-mail.

POST: Add Education

curl -X POST 'https://harvest.greenhouse.io/v1/candidates/{id}/educations'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "school_id": 459,
  "discipline_id": 940,
  "degree_id": 1230,
  "start_date": "2001-09-15T00:00:00.000Z",
  "end_date": "2004-05-15T00:00:00.000Z"
}

The above command returns a JSON response with a 201 status, structured like this:

{
  "id": 5690098,
  "school_name": "Siena College",
  "discipline": "Computer Science",
  "degree": "Bachelor's Degree",
  "start_date": "2001-09-15T00:00:00.000Z",
  "end_date": "2004-05-15T00:00:00.000Z"
}

Create a new education record

HTTP Request

POST https://harvest.greenhouse.io/v1/candidates/{id}/educations

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
school_idYesintegerThe ID of the college attended; from the GET schools endpoint
discipline_idYesintegerThe ID of the discipline of the candidate’s education; from the GET disciplines endpoint.
degree_idYesintegerThe type of degree received; from the GET degrees endpoint
start_dateYesDateTimeThe date the candidate began attendance. Timestamp must be in in ISO-8601 format.*
end_dateYesDateTimeThe date the candidate finished attendance. Timestamp must be in in ISO-8601 format.*

DELETE: Remove Education From Candidate

curl -X DELETE 'https://harvest.greenhouse.io/v1/candidates/{candidate_id}/educations/{education_id}'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above returns a JSON response, structured like this:

{
    "success": true,
    "message": "Education ID 2002247 destroyed."
}

Delete an education record by candidate and education id.

HTTP Request

DELETE https://harvest.greenhouse.io/v1/candidates/{candidate_id}/educations/{education_id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

POST: Add Employment

curl -X POST 'https://harvest.greenhouse.io/v1/candidates/{id}/employments'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "company_name": "Greenhouse",
  "title": "Engineer",
  "start_date": "2001-09-15T00:00:00.000Z",
  "end_date": "2004-05-15T00:00:00.000Z"
}

The above command returns a JSON response with a 201 status, structured like this:

{
  "id": 5690098,
  "company_name": "Greenhouse",
  "title": "Engineer",
  "start_date": "2001-09-15T00:00:00.000Z",
  "end_date": "2004-05-15T00:00:00.000Z"
}

Create a new employment record

HTTP Request

POST https://harvest.greenhouse.io/v1/candidates/{id}/employments

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
company_nameYesStringA free text field indicating an employer’s name
titleYesStringA free text field indicating the candidate’s title while at the employer.
start_dateYesDateTimeThe date the candidate began at employer. Timestamp must be in in ISO-8601 format.*
end_dateNoDateTimeThe date the candidate finished at employer. Timestamp must be in in ISO-8601 format.* An empty end_date indicates current employment.

DELETE: Remove Employment From Candidate

curl -X DELETE 'https://harvest.greenhouse.io/v1/candidates/{candidate_id}/employments/{employment_id}'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above returns a JSON response, structured like this:

{
    "success": true,
    "message": "Employment ID 823384 destroyed."
}

Delete an employment record by candidate and employment id.

HTTP Request

DELETE https://harvest.greenhouse.io/v1/candidates/{candidate_id}/employments/{employment_id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

POST: Add Prospect

curl -X POST 'https://harvest.greenhouse.io/v1/prospects'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "first_name": "John",
  "last_name": "Locke",
  "company": "The Tustin Box Company",
  "title": "Man of Mystery",
  "is_private": false,
  "phone_numbers": [
    {
      "value": "555-1212",
      "type": "mobile"
    }
  ],
  "addresses": [
    {
      "value": "123 Fake St.",
      "type": "home"
    }
  ],
  "email_addresses": [
    {
      "value": "john.locke+work@example.com",
      "type": "work"
    },
    {
      "value": "john.locke@example.com",
      "type": "personal"
    }
  ],
  "website_addresses": [
    {
      "value": "johnlocke.example.com",
      "type": "personal"
    }
  ],
  "social_media_addresses": [
    {
      "value": "linkedin.example.com/john.locke"
    },
    {
      "value": "@johnlocke"
    }
  ],
  "educations": [
    {
      "school_id": 459,
      "discipline_id": 940,
      "degree_id": 1230,
      "start_date": "2001-09-15T00:00:00.000Z",
      "end_date": "2004-05-15T00:00:00.000Z"
    }
  ],
  "employments": [
      {
          "company_name": "Greenhouse",
          "title": "Engineer",
          "start_date": "2012-08-15T00:00:00.000Z",
          "end_date": "2016-05-15T00:00:00.000Z"
      }
  ],
  "tags": [
    "Walkabout",
    "Orientation"
  ],
  "application": {
    "job_ids": [123, 456, 789],
    "source_id": 1234,
    "referrer": {
      "type": "id",
      "value": 770
    },
    "custom_fields": [],
    "attachments": []
  }
}

The above returns a JSON response, structured like this:

{
  "id": 29843268,
  "first_name": "John",
  "last_name": "Locke",
  "company": "The Tustin Box Company",
  "title": "Man of Mystery",
  "is_private": false,
  "created_at": "2016-12-21T19:45:01.467Z",
  "updated_at": "2016-12-21T19:45:01.907Z",
  "last_activity": "2016-12-21T19:45:01.867Z",
  "photo_url": null,
  "attachments": [],
  "application_ids": [
    38776657
  ],
  "phone_numbers": [
    {
      "value": "555-1212",
      "type": "mobile"
    }
  ],
  "addresses": [
    {
      "value": "123 Fake St.",
      "type": "home"
    }
  ],
  "email_addresses": [
    {
      "value": "john.locke@example.com",
      "type": "personal"
    },
    {
      "value": "john.locke+work@example.com",
      "type": "work"
    }
  ],
  "website_addresses": [
    {
      "value": "johnlocke.example.com",
      "type": "personal"
    }
  ],
  "social_media_addresses": [
    {
      "value": "@johnlocke"
    },
    {
      "value": "linkedin.example.com/john.locke"
    }
  ],
  "recruiter": null,
  "coordinator": null,
  "tags": [
    "Orientation",
    "Walkabout"
  ],
  "applications": [
    {
      "id": 38776657,
      "candidate_id": 29843268,
      "prospect": true,
      "applied_at": "2016-12-21T19:45:01.757Z",
      "rejected_at": null,
      "last_activity_at": "2016-12-21T19:45:01.867Z",
      "source": null,
      "location": null,
      "credited_to": null,
      "rejection_reason": null,
      "rejection_details": null,
      "jobs": [],
      "status": "active",
      "current_stage": null,
      "answers": [],
      "custom_fields": {
        "test": "A test value"
      },
      "keyed_custom_fields": {
         "test": {
            "name": "Test",
            "type": "long_text",
            "value": "A test value"
          }
        }
     }
  ],
  "educations": [
    {
      "id": 561226,
      "school_name": "Siena College",
      "discipline": "Computer Science",
      "degree": "Bachelor's Degree"
    }
  ],
  "employments": [
      {
          "id": 8485064,
          "company_name": "Greenhouse",
          "title": "Engineer",
          "start_date": "2012-08-15T00:00:00.000Z",
          "end_date": "2016-05-15T00:00:00.000Z"
      }
  ],
  "custom_fields": {
    "current_salary": "$123,000",
    "desired_salary": "$150,000"
  },
  "keyed_custom_fields": {
    "current_salary": {
      "name": "Current salary",
      "type": "short_text",
      "value": "$123,000"
    },
    "desired_salary": {
      "name": "Desired salary",
      "type": "short_text",
      "value": "$150,000"
    }
  }
}

Create a new prospect. The difference between a prospect and a candidate is that a prospect can be on no jobs or many jobs. A prospect application cannot be added to a job stage. When a prospect is ready to be added to a job stage, they can be converted to a candidate in Greenhouse. Alternatively, you can add a candidate application to a prospect’s profile by using the Add Candidate Application endpoint. The organization must be able to create prospects to set this field.

HTTP Request

POST https://harvest.greenhouse.io/v1/prospects

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
first_nameYesstringThe prospect’s first name
last_nameYesstringThe prospect’s last name
companyNostringThe prospect’s company
titleNostringThe prospect’s title
phone_numbers[]Nophone_numberArray of phone numbers. Passing an empty array will clear all.
addresses[]NoaddressArray of addresses. Passing an empty array will clear all.
email_addresses[]Noemail_addressArray of email addresses. Passing an empty array will clear all.
website_addresses[]Nowebsite_addressArray of website addresses. Passing an empty array will clear all.
social_media_addresses[]Nosocial_media_addressArray of social media addresses. Passing an empty array will clear all.
tags[]NostringArray of tags as strings. Passing an empty array will clear all.
custom_fields[]Nocustom_fieldArray of hashes containing new custom field values. Passing an empty array does nothing.
recruiterNoObjectAn object representing the prospect’s recruiter
recruiter[id]NoIntegerThe ID of the recruiter - either id or email must be present.
recruiter[email]NoStringThe email of the recruiter - either id or email must be present.
coordinatorNoObjectAn object representing the prospect’s coordinator
coordinator[id]NoIntegerThe ID of the coordinator - either id or email must be present.
coordinator[email]NoStringThe email of the coordinator - either id or email must be present.
custom_fieldsNoArrayArray of custom field value objects - See “Custom Field Parameters” under Edit candidate for parameters.
activity_feed_notesNoArrayAn array of activity feed objects. See Add Note for parameters.
applicationNoHashAs opposed to candidate, a prospect is a single application object that contains multiple job ids. A prospect in Greenhouse can be attached to zero or many jobs. If the request does not contain an application object, the person will be created as a jobless prospect. The source_id, referrer, custom_fields, and attachments parameters in this object match the format of the Add Application endpoint.
application[job_ids]NoArrayThis element is unique to the prospects endpoint. This contains an array of job ids to which the prospect will be assigned. Note that even if the application object is included, this may still be blank or omitted and the request will create a jobless prospect. A normal use case for this would be creating a jobless prospect but still wanting to attach their resume or identify their source.

See noteworthy response attributes.

PUT: Anonymize Candidate

curl -X PUT 'https://harvest.greenhouse.io/v1/candidates/{id}/anonymize?fields={field_names}'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns a JSON response, structured like this:

{
    "id": 53883394,
    "first_name": "Anonymized",
    "last_name": "53883394",
    "company": null,
    "title": null,
    "created_at": "2017-08-15T03:31:46.591Z",
    "updated_at": "2017-09-28T13:36:04.725Z",
    "last_activity": "2017-09-28T13:31:37.929Z",
    "is_private": false,
    "photo_url": "https://prod-heroku.s3.amazonaws.com/people/photos/053/883/394/original/corgi.jpg?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509197765&Signature=pr0qNjZvTvLCV2td9hebhEa7P3Y%3D",
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_28_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/person_attachments/data/077/815/020/original/John_Locke_Offer_Packet_09_28_2017.pdf?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509197765&Signature=rV%2FW668FnnG4EFGLJbHrnY%2B7Mvs%3D",
            "type": "offer_packet"
        }
    ],
    "application_ids": [
        69201279
    ],
    "phone_numbers": [],
    "addresses": [
        {
            "value": "123 City Street\nNew York, Ny 10001",
            "type": "home"
        }
    ],
    "email_addresses": [],
    "website_addresses": [
        {
            "value": "mysite.com",
            "type": "personal"
        }
    ],
    "social_media_addresses": [],
    "recruiter": {
        "id": 92120,
        "first_name": "Greenhouse",
        "last_name": "Admin",
        "name": "Greenhouse Admin",
        "employee_id": null
    },
    "coordinator": null,
    "tags": [
        "Python",
        "Ruby"
    ],
    "applications": [
        {
            "id": 69201279,
            "candidate_id": 53883394,
            "prospect": false,
            "applied_at": "2017-09-28T13:21:22.749Z",
            "rejected_at": null,
            "last_activity_at": "2017-09-28T13:31:37.929Z",
            "location": null,
            "source": {
                "id": 7,
                "public_name": "Indeed"
            },
            "credited_to": {
                "id": 566993,
                "first_name": "Jane",
                "last_name": "Smith",
                "name": "Jane Smith",
                "employee_id": null
            },
            "rejection_reason": null,
            "rejection_details": null,
            "jobs": [
                {
                    "id": 213967,
                    "name": "Head of Product"
                }
            ],
            "status": "active",
            "current_stage": {
                "id": 1567309,
                "name": "Application Review"
            },
            "answers": [],
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            }
        }
    ],
    "educations": [
        {
            "id": 561227,
            "school_name": "University of Michigan - Ann Arbor",
            "degree": "Bachelor's Degree",
            "discipline": "Computer Science"
        }
    ],
    "employments": [
        {
            "id": 8485064,
            "company_name": "Greenhouse",
            "title": "Engineer",
            "start_date": "2012-08-15T00:00:00.000Z",
            "end_date": "2016-05-15T00:00:00.000Z"
        }
    ],
    "custom_fields": {
        "desired_salary": null,
        "work_remotely": null,
        "graduation_year": null
    },
    "keyed_custom_fields": {
        "desired_salary": null,
        "work_remotely": null,
        "graduation_year_1": null
    }
}

Anonymize the data associated with a candidate. Please note that this endpoint is only available to customers with Enterprise-level accounts.

HTTP Request

PUT https://harvest.greenhouse.io/v1/candidates/{id}/anonymize?fields={field_names}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

Querystring Parameters

ParameterRequiredTypeDescription
fieldsYescomma-delimited stringThe set of field names that should be anonymized on the candidate from the following list: full_name, current_company, current_title, tags, phone_numbers, emails, social_media_links, websites, addresses, location, custom_candidate_fields, source, recruiter, coordinator, attachments, application_questions, referral_questions, notes, rejection_notes, email_addresses, activity_items, innotes, inmails, rejection_reason, scorecards_and_interviews, offers, credited_to, headline, all_offer_versions, follow_up_reminders, candidate_photo, custom_application_fields, education, employment, candidate_stage_data, prospect_owner, custom_rejection_question_fields, touchpoints, prospect_pool_and_stage, prospect_jobs, prospect_offices, prospect_offices_and_departments, and third_party_integrations

PUT: Merge Candidates

curl -X PUT 'https://harvest.greenhouse.io/v1/candidates/merge'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
    "primary_candidate_id": 73821,
    "duplicate_candidate_id": 839283
}

The above command returns a JSON response, structured like this:

{
    "id": 55961742,
    "first_name": "Justin",
    "last_name": "Locke",
    "company": "The Tustin Box Company",
    "title": "Man of Mystery",
    "created_at": "2017-09-07T22:54:06.629Z",
    "updated_at": "2017-09-28T13:41:43.655Z",
    "last_activity": "2017-09-28T13:41:43.631Z",
    "is_private": false,
    "photo_url": null,
    "attachments": [
        {
            "filename": "Justin Locke resume.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/person_attachments/data/048/999/636/original/Byron%20Sonnett%20resume.pdf?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509198103&Signature=Zc%2BenNvJyxH4FatQBRFz8248GUM%3D",
            "type": "resume"
        },
         {
            "filename": "Justin Locke cover leter.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/person_attachments/data/048/999/636/original/Byron%20Sonnett%20resume.pdf?AWSAccessKeyId=AKIAIK36UTOKQ5F2YNMQ&Expires=1509198103&Signature=Zc%2BenNvJyxH4FatQBRFz8248GUM%3D",
            "type": "cover_letter"
        }
    ],
    "application_ids": [
        67398864
    ],
    "phone_numbers": [
        {
            "value": "222-555-4608",
            "type": "home"
        }
    ],
    "addresses": [],
    "email_addresses": [
        {
            "value": "justin.locke@example.com",
            "type": "personal"
        }
    ],
    "website_addresses": [
        {
            "value": "example.com",
            "type": "other"
        }
    ],
    "social_media_addresses": [],
    "recruiter": null,
    "coordinator": null,
    "tags": [
        "Comp Sci"
    ],
    "applications": [
        {
            "id": 67398864,
            "candidate_id": 55961742,
            "prospect": false,
            "applied_at": "2017-09-07T23:00:25.746Z",
            "rejected_at": null,
            "last_activity_at": "2017-09-28T13:41:43.631Z",
            "location": {
                "address": "New York, New York, USA"
            },
            "source": {
                "id": 7,
                "public_name": "Indeed"
            },
            "credited_to": {
                "id": 92121,
                "first_name": "Jane",
                "last_name": "Smith",
                "name": "Jane Smith",
                "employee_id": "456"
            },
            "rejection_reason": null,
            "rejection_details": null,
            "jobs": [
                {
                    "id": 213967,
                    "name": "Product Manager"
                }
            ],
            "status": "active",
            "current_stage": {
                "id": 1567309,
                "name": "Application Review"
            },
            "answers": [],
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            }
        }
    ],
    "educations": [
        {
            "id": 561227,
            "school_name": "University of Michigan - Ann Arbor",
            "degree": "Bachelor's Degree",
            "discipline": "Computer Science"
        }
    ],
    "employments": [
        {
            "id": 8485064,
            "company_name": "Greenhouse",
            "title": "Engineer",
            "start_date": "2012-08-15T00:00:00.000Z",
            "end_date": "2016-05-15T00:00:00.000Z"
        }
    ],
    "custom_fields": {
        "desired_salary": "120K",
        "work_remotely": true,
        "graduation_year": "2018"
    },
    "keyed_custom_fields": {
        "desired_salary": {
            "name": "Desired Salary",
            "type": "short_text",
            "value": "120K"
        },
        "work_remotely": {
            "name": "Work Remotely",
            "type": "boolean",
            "value": true
        },
        "graduation_year_1": {
            "name": "Graduation Year",
            "type": "single_select",
            "value": "2018"
        }
    }
}

Merge two candidates into one.

HTTP Request

PUT https://harvest.greenhouse.io/v1/candidates/merge

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
primary_candidate_idYesintegerThe id of the first candidate that will be merged. This candidate will also be the result of the merge.
duplicate_candidate_idYesintegerThe id of the second candidate that will be merged. This candidate will cease to exist after the merge is complete.

Close Reasons

When closing an opening, it is possible to designate the reason the opening is being closed. This might be “Filled” or “Cancelled” or some other reason. These reasons are configured in Greenhouse.

The close reason object

{
  "id": 230,
  "name": "Hired"
}

Noteworthy attributes

AttributeDescription
idThe close reason’s unique identifier. This is the ID that would be used in POST or PATCH statements involving close reasons.
nameThe name of the close reason

GET: List Close Reasons

List all of an organization’s close reasons.

curl -X GET 'https://harvest.greenhouse.io/v1/close_reasons'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 365,
    "name": "Hired"
  },
  {
    "id": 366,
    "name": "Backfill"
  },
  {
    "id": 367,
    "name": "Order cancelled"
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/close_reasons


See noteworthy response attributes.

Custom Fields

An organization’s custom_fields.

The custom field object

{
  "id": 123456,
  "name": "Custom Field Name",
  "field_type": "job",
  "priority": 1,
  "value_type": "single_select",
  "private": true,
  "required": false,
  "require_approval": true,
  "trigger_new_version": false,
  "name_key": "custom_field_name",
  "custom_field_options": [
    {
      "id": 123,
      "name": "Name One",
      "priority": 1
    },
    {
      "id": 234,
      "name": "Name Two",
      "priority": 2
    }
  ]
}

Noteworthy attributes

AttributeDescription
idThe custom field’s unique identifier
nameThe field’s name in Greenhouse
activeBoolean value which is false if the custom field has been deleted, true otherwise.
field_typeOne of job, candidate, application, offer, rejection_question, referral_question. This is also included in the URL as an argument, which will return only custom fields that match the given type.
priorityNumeric field used for ordering in Greenhouse.
value_typeOne of short_text, long_text, yes_no, single_select, multi_select, currency, currency_range, number, number_range, date, url, or user
privateBoolean value to say if this field is private in Greenhouse.
requiredThe object this field exists on can not be saved if this value is not set.
require_approvalOnly applicable to job custom fields, changes to this fields requires an approval flow in Greenhouse to be re-done.
trigger_new_versionOnly applicable to offer custom fields, changes to this field creates a new offer version.
name_keyListed as “immutable field key” in Greenhouse, this value is based of the name of the field when it is created and does not change as the field’s name is later updated.
custom_field_optionsFor single_select and multi_select field_types, this is the list of options for that select.
custom_field_options.priorityNumeric value used for ordering the custom field options.

GET: List Custom Fields

curl 'https://harvest.greenhouse.io/v1/custom_fields/{field_type}'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 123456,
    "name": "Custom Field Name",
    "active": true,
    "field_type": "job",
    "priority": 1,
    "value_type": "single_select",
    "private": true,
    "required": false,
    "require_approval": true,
    "trigger_new_version": false,
    "name_key": "custom_field_name",
    "custom_field_options": [
      {
        "id": 123,
        "name": "Name One",
        "priority": 1
      },
      {
        "id": 234,
        "name": "Name Two",
        "priority": 2
      }
    ]
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/custom_fields/{field_type}

URL parameters

ParameterDescription
field_typeReturns only custom fields of this type. For example, if “offer” is included in the URL as the field_type, the endpoint will only return custom fields with the “offer” field type. One of: offer, candidate, application, job, rejection_question, referral_question.

Querystring parameters

ParameterDescription
include_inactiveWhen true, include inactive custom fields. Otherwise excludes inactive custom fields. Defaults to false.


See noteworthy response attributes.

This endpoint supports pagination. See the Pagination section for more detail.

GET: Retrieve Custom Field

curl 'https://harvest.greenhouse.io/v1/custom_field/{id}'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

{
  "id": 123456,
  "name": "Custom Field Name",
  "active": true,
  "field_type": "job",
  "priority": 1,
  "value_type": "single_select",
  "private": true,
  "required": false,
  "require_approval": true,
  "trigger_new_version": false,
  "name_key": "custom_field_name",
  "custom_field_options": [
    {
      "id": 123,
      "name": "Name One",
      "priority": 1
    },
    {
      "id": 234,
      "name": "Name Two",
      "priority": 2
    }
  ]
}

HTTP Request

GET https://harvest.greenhouse.io/v1/custom_field/{id}

URL Parameters

ParameterDescription
idThe ID of the custom field to retrieve


See noteworthy response attributes.

The custom field options object

Refers to the options available for single-select and multi-select custom fields.

{
  "id": 123456,
  "name": "Option A",
  "priority": 0
}

Noteworthy attributes

AttributeDescription
priorityNumeric field used for ordering in Greenhouse.

GET: List Custom Field Options

curl 'https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 123456,
    "name": "Option A",
    "priority": 0
  },
  {
    "id": 123457,
    "name": "Option B",
    "priority": 1
  },
  {
    "id": 123458,
    "name": "Option C",
    "priority": 2
  }
]

Given a single select or multi select custom field, return all its options.

HTTP Request

GET https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options

Querystring parameters

ParameterDescription
typeOne of all, active, or inactive. Inactive returns only custom field options that have been deleted. Active is the default and returns all custom field options currently active. All returns both active and inactive. If this isn’t included, active fields will be returned.


This endpoint supports pagination. See the Pagination section for more detail.

POST: Create Custom Field Options

curl -X POST 'https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "options": [
    {"name": "Option A", "priority": 5},
    {"name": "Option B", "priority": 6},
    {"name": "Option C", "priority": 7}
  ]
}

The above returns a success message on success with a 201 response.

{
    "success": true
}

Add additional options to a single select or multi select custom field.

HTTP Request

POST https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
optionsYesarrayAn array of one or many new custom field options.
nameYesstringThe name of the new custom field option. If a new field is added with the same name as an existing custom field option in this custom field, it will be ignored. No error will be raised in this case.
priorityYesintegerThis is used to order the custom fields in Greenhouse.


**This returns a 201 on success. It does not return the objects created.

PATCH: Update Custom Field Options

curl -X PATCH 'https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "options": [
    {
      "id": 123, 
      "name": "Option A", 
      "priority": 5
    },
    {
      "id": 234, 
      "name": "Option B", 
      "priority": 6
    },
    {
      "id": 345, 
      "name": "Option C", 
      "priority": 7
    }
  ]
}

The above request returns a JSON success message.

{
    "success": true
}

Update the names or priorities of existing options in a single select or multi select custom field.

HTTP Request

PATCH https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
optionsYesarrayAn array of one or many new custom field options.
idYesintegerThe ID of the custom field option that will be updated.
nameNostringIf included, the custom field option with this ID will be updated to this name. This can not duplicate the name of any other option in this field or any option in this request.
priorityNointegerIf included, The custom field option with this ID will be updated with this value.


DELETE: Remove Custom Field Options

curl -X DELETE 'https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options'
  -H "On-Behalf-Of: {greenhouse user ID}"
  -H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "option_ids": [
    85709, 85710
  ]
}

The above request is idempotent. It will return a message with a 200 response and a message stating how many of the IDs were deleted and how many were not found.

{
  "message": "3 option(s) deleted. 1 option(s) not found."
}

Destroy custom field options

HTTP Request

DELETE https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
option_idsYesarrayAn array of the custom field option ids to be removed.


* Note this does not return a list of option_ids that were not found. It only returns a number of options that were not processed. If you were to run the same exact command twice in a row, the only difference would be that on the second run, the message would inform you that an ID was not found.

Departments

The department object

An organization’s departments.

With render_as=list (default)

{
  "id": 12345,
  "name": "Technology",
  "parent_id": null,
  "child_ids": [
      34065,
      25908
  ],
  "external_id": "89076"
}

With render_as=tree

{
  "id": 12345,
  "name": "Technology",
  "children": [
    {
      "id": 34065,
      "name": "Design",
      "children": [],
      "external_id": "32526"
    },
    {
      "id": 25908,
      "name": "Engineering",
      "children": [               
        {
            "id": 14510,
            "name": "Third-Level Department",
            "children": [
              {
                  "id": 14502,
                  "name": "Strategy",
                  "children": [],
                  "external_id": null
              }
            ],
            "external_id": "56735"
        }
      ],
      "external_id": "47658"
    }
  ],
  "external_id": "26758"
}

Noteworthy attributes

AttributeDescription
idThe department’s unique identifier
nameThe department’s name
external_idAn arbitrary ID provided by an external source; does not map to another entity in Greenhouse.

GET: List Departments

List all of an organization’s departments.

curl 'https://harvest.greenhouse.io/v1/departments'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this, with render_as=list (default)

[
  {
    "id": 12345,
    "name": "Technology",
    "parent_id": null,
    "child_ids": [
        34065,
        25908
    ],
    "external_id": "89076"
  }
  {
    "id": 67890,
    "name": "Administration",
    "parent_id": 54647,
    "child_ids": [],
    "external_id": null
  }
]

With render_as=tree

[
  {
    "id": 12345,
    "name": "Technology",
    "children": [
      {
        "id": 34065,
        "name": "Design",
        "children": [],
        "external_id": "32526"
      },
      {
        "id": 25908,
        "name": "Engineering",
        "children": [               
          {
              "id": 14510,
              "name": "Third-Level Department",
              "children": [],
              "external_id": "56735"
          }
        ],
        "external_id": "47658"
      }
    ],
    "external_id": "26758"
  }
  {
    "id": 67890,
    "name": "Administration",
    "parent_id": 54647,
    "child_ids": [],
    "external_id": null
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/departments

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
render_asThis parameter defines how to represent the list of departments. The default value is ‘list’, which returns a flat list of departments. If this is set to 'tree’, departments are represented in a tree-like structure where they may include sub-departments as children.


See noteworthy response attributes.

GET: Retrieve Department

curl 'https://harvest.greenhouse.io/v1/departments/{id}'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

With render_as=list (default)

{
  "id": 12345,
  "name": "Technology",
  "parent_id": null,
  "child_ids": [
      34065,
      25908
  ],
  "external_id": "89076"
}

With render_as=tree

{
  "id": 12345,
  "name": "Technology",
  "children": [
    {
      "id": 34065,
      "name": "Design",
      "children": [],
      "external_id": "32526"
    },
    {
      "id": 25908,
      "name": "Engineering",
      "children": [               
        {
            "id": 14510,
            "name": "Third-Level Department",
            "children": [],
            "external_id": "56735"
        }
      ],
      "external_id": "47658"
    }
  ],
  "external_id": "26758"
}
{
  "id": 67890,
  "name": "Administration",
  "parent_id": 54647,
  "child_ids": [],
  "external_id": null
}

Retrieve a department by its id.

HTTP Request

GET https://harvest.greenhouse.io/v1/departments/{id}

URL Parameters

ParameterDescription
idThe ID of the department to retrieve

Querystring parameters

ParameterDescription
render_asThis parameter defines how to represent the list of departments. The default value is 'list’, which returns a flat list of departments. If this is set to 'tree’, departments are represented in a tree-like structure where they may include sub-departments as children.


See noteworthy response attributes.

PATCH: Edit Department

curl -X PATCH 'https://harvest.greenhouse.io/v1/departments/{id}'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
   "name": "Engineering",
   "external_id": "EXTERNAL_ID_1234"
}

The above command returns a JSON response, structured like this:

{
  "id": 45644,
  "name": "Engineering",
  "parent_id": null,
  "child_ids": [
      34065,
      25908
  ],
  "external_id": "EXTERNAL_ID_1234"
}

Edit a department’s basic information.

HTTP Request

PATCH https://harvest.greenhouse.io/v1/departments/{id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
nameYesstringThe department’s name. If included, this cannot be blank.
external_id*NostringThe department’s external ID. If included, this must be unique to this department within the organization.

* - If the external id feature is not enabled for your organization, attempting to edit this field will raise an API Error.

POST: Add Department

curl -X POST 'https://harvest.greenhouse.io/v1/departments
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "name": "A New Department",
  "parent_id": 12345,
  "external_id": "456454"
}

The above command returns a JSON response, structured like this:

{
  "id": 34535,
  "name": "A New Department",
  "parent_id": 12345,
  "child_ids": [],
  "external_id": "456454"
}

Create a new department

HTTP Request

POST https://harvest.greenhouse.io/v1/departments

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes. Must be a user who can create departments.

JSON Body Parameters

ParameterRequiredTypeDescription
nameyesstringThe name of your new department. Must be less than 255 characters and unique within your organization.
parent_id*nonumberThe department id for the new department to be nested under. If this isn’t included, the department will be created at the top level.
external_id**nostringThe external_id for the office.

* - The tiered department feature is available only for customers with the Pro or Enterprise Greenhouse Recruiting package. Use of this field will return an error for other Greenhouse Recruiting customers.

** - The external_id feature is available only for customers with the Enterprise Greenhouse Recruiting package. Use of this field will return an error for other Greenhouse Recruiting customers.

Education

These endpoints are used to manage the list of education fields in Greenhouse.

The education objects

Each of the education objects contain an id, name, and priority. When ordering occurs, the items are organized by their priority number. { "id": 1234, "name": "Siena College", "priority": 1 }

GET: List Degrees

curl 'https://harvest.greenhouse.io/v1/degrees' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
    {
        "id": 123,
        "name": "Bachelor's Degree",
        "priority": 0
    },
    {
        "id": 234,
        "name": "Master's Degree",
        "priority": 1
    }
]

List all this organization’s degree levels.

HTTP Request

GET https://harvest.greenhouse.io/v1/degrees

This endpoint retrieves all the degree and/or education levels for this organization, sorted by priority.

See education object.

GET: List Disciplines

curl 'https://harvest.greenhouse.io/v1/disciplines' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
    {
        "id": 123,
        "name": "Accounting",
        "priority": 0
    },
    {
        "id": 234,
        "name": "Biology",
        "priority": 1
    }
]

List all this organization’s disciplines.

HTTP Request

GET https://harvest.greenhouse.io/v1/disciplines

This endpoint retrieves all the disciplines for this organization, sorted by priority.

See education object.

GET: List Schools

curl 'https://harvest.greenhouse.io/v1/schools' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
    {
        "id": 123,
        "name": "Siena College",
        "priority": 0
    },
    {
        "id": 234,
        "name": "Union College",
        "priority": 1
    }
]

List all this organization’s schools.

HTTP Request

GET https://harvest.greenhouse.io/v1/schools

This endpoint retrieves all the schools for this organization, sorted by priority.

See education object.

EEOC

The EEOC object

Every application may have zero or one EEOC object.

{
  "application_id": 286,
  "candidate_id": 406,
  "race": {
    "id": 7,
    "description": "Two or More Races"
  },
  "gender": {
    "id": 1,
    "description": "Male"
  },
  "veteran_status": {
    "id": 3,
    "message": "I don't wish to answer"
  },
  "disability_status": {
    "id": 1,
    "description": "Yes, I have a disability (or previously had a disability)"
  },
  "submitted_at": "2017-01-29T15:09:46.806Z"
}

Noteworthy attributes

AttributeDescription
application_idApplication ID
candidate_idThe ID of the candidate who is applying for the job associated with this application.
raceSee the EEOC Reference below
genderSee the EEOC Reference below
veteran_statusSee the EEOC Reference below
disability_statusSee the EEOC Reference below
submitted_atThe timestamp in ISO-8601 at which the EEOC data was submitted.

EEOC Reference

Race

description
American Indian or Alaskan Native
Asian
Black or African American
Hispanic or Latino
White
Native Hawaiian or Other Pacific Islander
Two or More Races
Decline To Self Identify

Gender

description
Male
Female
Decline To Self Identify

Veteran Status

description
I am not a protected veteran
I identify as one or more of the classifications of a protected veteran
I don’t wish to answer

Disability Status

description
Yes, I have a disability (or previously had a disability)
No, I don’t have a disability
I don’t wish to answer

GET: List EEOC

curl 'https://harvest.greenhouse.io/v1/eeoc'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "application_id": 286,
    "candidate_id": 406,
    "race": {
      "id": 7,
      "description": "Two or More Races"
    },
    "gender": {
      "id": 1,
      "description": "Male"
    },
    "veteran_status": {
      "id": 3,
      "message": "I don't wish to answer"
    },
    "disability_status": {
      "id": 1,
      "description": "Yes, I have a disability (or previously had a disability)"
    },
    "submitted_at": "2017-01-29T15:09:46.806Z"
  },
  {
    "application_id": 287,
    "candidate_id": 342,
    "race": {
      "id": 7,
      "description": "Two or More Races"
    },
    "gender": {
      "id": 2,
      "description": "Female"
    },
    "veteran_status": null,
    "disability_status": {
      "id": 1,
      "description": "Yes, I have a disability (or previously had a disability)"
    },
    "submitted_at": "2017-01-30T17:10:32.432Z"
  }
]

List all of an organization’s EEOC data.

HTTP Request

GET https://harvest.greenhouse.io/v1/eeoc

Query string parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
submitted_beforeReturn only EEOC data submitted before this timestamp. Timestamp must be in ISO-8601 format.
submitted_afterReturn only EEOC data submitted at or after this timestamp. Timestamp must be in ISO-8601 format.

This endpoint supports pagination. See the Pagination section for more detail.

GET: Retrieve EEOC Data for Application

curl 'https://harvest.greenhouse.io/v1/applications/{id}/eeoc'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

{
  "application_id": 286,
  "candidate_id": 406,
  "race": {
    "id": 7,
    "description": "Two or More Races"
  },
  "gender": {
    "id": 1,
    "description": "Male"
  },
  "veteran_status": {
    "id": 3,
    "message": "I don't wish to answer"
  },
  "disability_status": {
    "id": 1,
    "description": "Yes, I have a disability (or previously had a disability)"
  },
  "submitted_at": "2017-01-29T15:09:46.806Z"
}

Retrieve an application’s EEOC data by an application ID.

HTTP Request

GET https://harvest.greenhouse.io/v1/applications/{id}/eeoc

URL Parameters

ParameterDescription
idID of the application whose EEOC data you want to retrieve.

Email Templates

An organization’s email templates.

The email template object

{
  "id": 48765,
  "name": "Default Scorecard Reminder",
  "description": "To be sent to an interviewer when their scorecard is due.",
  "default": true,
  "updated_at": "2018-06-01T17:04:13.598Z",
  "created_at": "2015-11-18T22:26:32.154Z",
  "type": "scorecard_reminder",
  "from": null,
  "cc": [
      "example.user@example.com"
  ],
  "body": null,
  "html_body": "<p>Hello,</p>\r\n<p>Please help us keep our hiring on track!</p>\r\n<p>Send in your feedback now for the interview you conducted earlier today with {{CANDIDATE_NAME}}.</p>\r\n<p>It's easy - just visit the following link to fill out your scorecard online: {{SCORECARD_LINK}}</p>\r\n<p>Thanks,<br /> {{ORGANIZER_NAME}}</p>",
  "user": null
}

Noteworthy attributes

AttributeDescription
idThe email template’s unique identifier
typeOne of: new_candidate, weekly_status, daily_recruiting, stage_transition, new_scorecard, new_referral, agency_candidate_status, agency_candidate_stage, take_home_test_email, candidate_auto_reply, candidate_rejection, scorecard_reminder, interviewer_invite, candidate_email, team_email, none, extending_offer, new_agency_submission, non_admin_welcome, job_admin_welcome, site_admin_welcome, prospect_referral_receipt, candidate_referral_receipt, candidate_availability_request, candidate_availability_confirmation
fromThe user who is set to send the email. If the from address can change based on which user took an action in Greenhouse (e.g. scorecard reminders sent from the person who scheduled the interview), this field will be null.
bodyThe plain text body of the e-mail (may be null).
userThe user this template belongs to. If null, this is an ‘organization wide’ template available to everyone.
html_bodyThe body of the e-mail with html styling code (may be null).

GET: List Email Templates

List all of an organization’s email templates.

curl 'https://harvest.greenhouse.io/v1/email_templates/' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 48765,
    "name": "Default Scorecard Reminder",
    "description": "To be sent to an interviewer when their scorecard is due.",
    "default": true,
    "updated_at": "2018-06-01T17:04:13.598Z",
    "created_at": "2015-11-18T22:26:32.154Z",
    "type": "scorecard_reminder",
    "from": null,
    "cc": [
        "example.user@example.com"
    ],
    "body": null,
    "html_body": "<p>Hello,</p>\r\n<p>Please help us keep our hiring on track!</p>\r\n<p>Send in your feedback now for the interview you conducted earlier today with {{CANDIDATE_NAME}}.</p>\r\n<p>It's easy - just visit the following link to fill out your scorecard online: {{SCORECARD_LINK}}</p>\r\n<p>Thanks,<br /> {{ORGANIZER_NAME}}</p>",
    "user": null
  },
  {
    "id": 200008,
    "name": "Personal Candidate Email Template",
    "description": "To email candidates",
    "default": false,
    "updated_at": "2018-06-01T17:08:03.320Z",
    "created_at": "2018-06-01T17:08:03.320Z",
    "type": "candidate_email",
    "from": "{{MY_EMAIL_ADDRESS}}",
    "cc": [],
    "body": null,
    "html_body": "Hi&nbsp;{{CANDIDATE_FIRST_NAME}},<br /><br />Please let me know if you're still interested in&nbsp;{{JOB_NAME}}.<br /><br />Thank you!<br /><br />{{MY_SIGNATURE}}",
    "user": {
        "id": 297349,
        "first_name": "Jane",
        "last_name": "Smith",
        "name": "Jane Smith",
        "employee_id": "12345"
    }
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/email_templates

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
created_beforeReturn only email templates that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_afterReturn only email templates that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_beforeReturn only email templates that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_afterReturn only email templates that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.


See noteworthy response attributes.

GET: Retrieve Email Template

curl 'https://harvest.greenhouse.io/v1/email_templates/{id}' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

{
  "id": 48765,
  "name": "Default Scorecard Reminder",
  "description": "To be sent to an interviewer when their scorecard is due.",
  "default": true,
  "updated_at": "2018-06-01T17:04:13.598Z",
  "created_at": "2015-11-18T22:26:32.154Z",
  "type": "scorecard_reminder",
  "from": null,
  "cc": [
      "example.user@example.com"
  ],
  "body": null,
  "html_body": "<p>Hello,</p>\r\n<p>Please help us keep our hiring on track!</p>\r\n<p>Send in your feedback now for the interview you conducted earlier today with {{CANDIDATE_NAME}}.</p>\r\n<p>It's easy - just visit the following link to fill out your scorecard online: {{SCORECARD_LINK}}</p>\r\n<p>Thanks,<br /> {{ORGANIZER_NAME}}</p>",
  "user": null
}

Retrieve an email template by its id.

HTTP Request

GET https://harvest.greenhouse.io/v1/email_templates/{id}

URL Parameters

ParameterDescription
idThe ID of the email template to retrieve


See noteworthy response attributes.

Job Openings

This endpoint is used to managing openings on jobs.

The job opening object

[
    {
        "id": 123,
        "opening_id": "OPENED-1",
        "status": "open",
        "opened_at": "2015-11-19T19:53:32.565Z",
        "closed_at": null,
        "application_id": null,
        "close_reason": null
    },
    {
        "id": 123,
        "opening_id": "CLOSED-1",
        "status": "closed",
        "opened_at": "2015-11-19T19:53:32.565Z",
        "closed_at": "2015-12-14T19:53:32.565Z",
        "application_id": 65565,
        "close_reason": {
          "id": 678,
          "name": "Hired - Backfill"
        }
    }
]

Noteworthy Attributes

AttributeDescription
idThe opening’s unique identifier
opening_idThis is a text string used to identify the opening. This is defined by the users and may be null.
statusEither “open” or “closed”
opened_atThis is the date and time this opening was created.
closed_atThis is when the opening was closed; usually via the opening being filled. This should be null for opened openings.
application_idThe application that was used to fill this opening. This should only be set on a closed opening, null otherwise.

GET: List Job Openings

curl 'https://harvest.greenhouse.io/v1/jobs/{job_id}/openings' -H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 123,
    "opening_id": "OPENED-1",
    "status": "open",
    "opened_at": "2015-11-19T19:53:32.565Z",
    "closed_at": null,
    "application_id": null,
    "close_reason": null
  },
  {
    "id": 123,
    "opening_id": "CLOSED-1",
    "status": "closed",
    "opened_at": "2015-11-19T19:53:32.565Z",
    "closed_at": "2015-12-14T19:53:32.565Z",
    "application_id": 65565,
    "close_reason": {
      "id": 678,
      "name": "Hired - Backfill"
    }
  }
]

List all of a job’s openings

HTTP Request

GET https://harvest.greenhouse.io/v1/jobs/{job_id}/openings

URL Paramters

ParameterDescription
job_idThe ID of the job for which you want to retrieve openings.

Querystring Parameters

ParameterDescription
statusMay contain either “opened” or “closed”; when set will return only open or closed openings, respectively. Returns all openings if this isn’t set or set to an unrecognized value.

This endpoint supports pagination. See the Pagination section for more detail.

See noteworthy response attributes.

GET: Single Opening For Job

curl 'https://harvest.greenhouse.io/v1/jobs/{job_id}/openings/{id}' -H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

{
    "id": 123,
    "opening_id": "OPENED-1",
    "status": "open",
    "opened_at": "2015-11-19T19:53:32.565Z",
    "closed_at": null,
    "application_id": null,
    "close_reason": null
}

Retrieve the information for a single opening.

HTTP Request

GET https://harvest.greenhouse.io/v1/jobs/{job_id}/openings/{id}

URL Parameters

ParameterDescription
job_idThe ID of the job for which you want to retrieve openings.
idThe ID of the opening you want to retrieve. Note: this is NOT the opening_id which is mutable and defined by Greenhouse users, but the id of an opening, which is unique to that opening and not mutable.

See noteworthy response attributes.

DELETE: Destroy Openings

curl -X DELETE 'https://harvest.greenhouse.io/v1/jobs/{job_id}/openings'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
{
    "ids": [123, 456, 789]
}

HTTP Request

DELETE https://harvest.greenhouse.io/v1/jobs/{job_id}/openings

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
idsyesArrayAn array of opening ids to delete. Important to note that these are not opening_id from the other endpoints, but the unique id identifier.

Note: Closed/Filled openings can’t be destroyed. This request is idempotent and will return the number of items destroyed, the number of closed items that couldn’t be destroyed, and the number of IDs that could not be found. If you were to run the same request twice, the destroyed ID count would decrease and the invalid ID count would increase.

The above returns a JSON response, structured like this

{
    "success": "2 opening(s) destroyed. 1 opening(s) were closed and not destroyed. 0 id(s) were not found."
}

PATCH: Edit Openings

curl -X PATCH 'https://harvest.greenhouse.io/v1/jobs/{job_id}/openings/{d}'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
{
    "opening_id": "abc-123",
    "status": "closed",
    "close_reason_id": 1234
}

HTTP Request

PATCH https://harvest.greenhouse.io/v1/jobs/{job_id}/openings/{id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

URL Parameters

ParameterDescription
job_idThe ID of the job on which to add new openings.
idThe ID of the opening. Note this is the immutable internal id, and not the free-text “opening_id” from the JSON body.

JSON Body Parameters

ParameterRequiredTypeDescription
opening_idnostringThis is a string that contains an opening_id. This may be a blank string. Changing an opening_id may re-trigger approvals. For approvals to start recruiting, this will reset approvals only if the job is in draft mode. If the job is open for hiring, these approvals will not reset. For official job approvals, this will reset approvals only if the job is open.
statusnostringThis can be used to set an open opening to closed by using the word “closed”. Status may only be used to set an open opening to closed. It does not accept any other value and cannot be used to re-open a closed opening. If the last opening is closed, it will close the hiring plan.
close_reason_idnointegerWhen closing, you may provide a close_reason_id. Providing a close_reason_id without closing the opening will return an error.

Note: Only open openings may be patched. Attempting to patch a closed opening will return an error. If the job is closed at the same time the opening_id is changed, approvals will be ignored in favor of closing the opening.

The above returns a JSON response, structured like this:

{
    "success": "true"
}

POST: Create New Openings

curl -X POST 'https://harvest.greenhouse.io/v1/jobs/{job_id}/openings'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
{
    "openings": [
      {"opening_id": "abc-123"},
      {"opening_id": null}
    ]
}

HTTP Request

POST https://harvest.greenhouse.io/v1/jobs/{job_id}/openings

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

URL Parameters

ParameterDescription
job_idThe ID of the job on which to add new openings.

JSON Body Parameters

ParameterRequiredTypeDescription
openingsyesArrayThis an array of opening IDs, which contain one element.
openings.opening_idyesArrayThis is a string that contains an opening_id. One new opening will be created for each hash element in the array. Opening ID is not required to have a string value and may be null. Greenhouse has an internal limit of 100 open openings. If you attempt to create more than 100 openings in a single request, or if this request would create more than 100 open openings, the request will fail.

Note: Adding new openings may re-trigger approvals. For approvals to start recruiting, this will reset approvals only if the job is in draft mode. If the job is open for hiring, these approvals will not reset. For official job approvals, this will reset approvals only if the job is open.

The above returns a JSON response, structured like this:

{
    "openings": [
        {
            "id": 123456,
            "opening_id": "abc-123",
            "open_date": "2017-10-02T19:53:32.565Z"
        },
        {
            "id": 123457,
            "opening_id": null,
            "open_date": "2017-10-02T19:53:32.565Z"
        }
    ]
}

Job Posts

Describes the online job posts for an organization’s jobs (as seen on the Job Board).

The job post object

{
  "id": 123,
  "title": "Button Pusher",
  "location": {
    "name": "The Island"
  },
  "internal": true,
  "external": false,
  "active": true,
  "live": true,
  "job_id": 1234,
  "content": "<p>Do you want to save the world? &nbsp;If so, apply today!</p>",
  "internal_content": "<p>Do you want to save the world? &nbsp;If so, apply today!</p>",
  "updated_at": "2016-11-21T15:39:24Z",
  "created_at": "2014-04-01T17:56:19Z",
  "questions": [
    {
      "required": true,
      "private": false,
      "label": "First Name",
      "name": "first_name",
      "type": "short_text",
      "values": [],
      "description": null
    },
    {
      "required": true,
      "private": false,
      "label": "Last Name",
      "name": "last_name",
      "type": "short_text",
      "values": [],
      "description": null
    },
    {
      "required": true,
      "private": false,
      "label": "Email",
      "name": "email",
      "type": "short_text",
      "values": [],
      "description": null
    },
    {
      "required": false,
      "private": false,
      "label": "Phone",
      "name": "phone",
      "type": "short_text",
      "values": [],
      "description": null
    },
    {
      "required": true,
      "private": false,
      "label": "Resume",
      "name": "resume",
      "type": "attachment",
      "values": [],
      "description": null
    },
    {
      "required": false,
      "private": false,
      "label": "Cover Letter",
      "name": "cover_letter",
      "type": "attachment",
      "values": [],
      "description": null
    },
    {
      "required": false,
      "private": false,
      "label": "Have you ever won the lottery?",
      "name": "question_234567",
      "type": "boolean",
      "values": [
        {
          "value": 0,
          "label": "No"
        },
        {
          "value": 1,
          "label": "Yes"
        }
      ],
      "description": "<p>Please select Yes or No.</p>"
    },
    {
      "required": false,
      "private": true,
      "label": "Do you know what 'the numbers' are?",
      "type": "multi_select",
      "name": "question_345678[]",
      "values": [
        {
          "value": 862,
          "label": "Yes"
        },
        {
          "value": 863,
          "label": "No"
        },
        {
          "value": 864,
          "label": "Maybe"
        }
      ],
      "description": null
    },
    {
      "required": true,
      "private": false,
      "label": "LinkedIn Profile",
      "name": "question_45678",
      "type": "short_text",
      "values": [],
      "description": "<p>Please enter the URL for your LinkedIn profile.</p>"
    },
    {
      "required": true,
      "private": false,
      "label": "How did you hear about this job?",
      "name": "question_56789",
      "type": "short_text",
      "values": [],
      "description": null
    }
  ]
}

Noteworthy attributes

AttributeDescription
idJob post ID
activeIf false, this job post has been deleted.
internalIf true, this job post has been posted (or is to be posted) on an internal job board.
externalIf true, this job post has been posted (or is to be posted) on an external job board.
job_idThe ID of the job that this job post is for.
contentThe text of the job post as posted to the external job board.
internal_contentThe text of the job post if posted to the internal job board, if different than the external job board.
questionsAn array of questions associated with this job post.
questions.nameWhen submitting applications through the Job Board API, this is the name of the POST parameter used to submit questions. Custom questions are prefixed with “question_” while Greenhouse standard application questions have a consistent name for every job post.

GET: List Job Posts

curl 'https://harvest.greenhouse.io/v1/job_posts' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 123,
    "title": "Button Pusher",
    "location": {
      "name": "The Island"
    },
    "internal": true,
    "external": false,
    "active": true,
    "live": true,
    "job_id": 1234,
    "content": "<p>Do you want to save the world? &nbsp;If so, apply today!</p>",
    "internal_content": "<p>Do you want to save the world? &nbsp;If so, apply today!</p>",
    "updated_at": "2016-11-21T15:39:24Z",
    "created_at": "2014-04-01T17:56:19Z",
    "questions": [
      {
        "required": true,
        "private": false,
        "label": "First Name",
        "name": "first_name",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "Last Name",
        "name": "last_name",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "Email",
        "name": "email",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": false,
        "private": false,
        "label": "Phone",
        "name": "phone",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "Resume",
        "name": "resume",
        "type": "attachment",
        "values": [],
        "description": null
      },
      {
        "required": false,
        "private": false,
        "label": "Cover Letter",
        "name": "cover_letter",
        "type": "attachment",
        "values": [],
        "description": null
      },
      {
        "required": false,
        "private": false,
        "label": "Have you ever won the lottery?",
        "name": "question_234567",
        "type": "boolean",
        "values": [
          {
            "value": 0,
            "label": "No"
          },
          {
            "value": 1,
            "label": "Yes"
          }
        ],
        "description": "<p>Please select Yes or No.</p>"
      },
      {
        "required": false,
        "private": true,
        "label": "Do you know what 'the numbers' are?",
        "type": "multi_select",
        "name": "question_345678[]",
        "values": [
          {
            "value": 862,
            "label": "Yes"
          },
          {
            "value": 863,
            "label": "No"
          },
          {
            "value": 864,
            "label": "Maybe"
          }
        ],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "LinkedIn Profile",
        "name": "question_45678",
        "type": "short_text",
        "values": [],
        "description": "<p>Please enter the URL for your LinkedIn profile.</p>"
      },
      {
        "required": true,
        "private": false,
        "label": "How did you hear about this job?",
        "name": "question_56789",
        "type": "short_text",
        "values": [],
        "description": null
      }
    ]
  }
]

List all of an organization’s job posts.

HTTP Request

GET https://harvest.greenhouse.io/v1/job_posts

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
created_beforeReturn only job posts that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_afterReturn only job posts that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_beforeReturn only job posts that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_afterReturn only job posts that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.
liveIf true, return only live job posts.
activeIf true, only return active job posts. If false, only return deleted job posts. When omitted, return both active and deleted job posts.


See noteworthy response attributes.

GET: Retrieve Job Post

curl 'https://harvest.greenhouse.io/v1/job_posts/{id}' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

{
    "id": 123,
    "title": "Button Pusher",
    "location": {
        "name": "The Island"
    },
    "internal": true,
    "external": false,
    "active": true,
    "live": true,
    "job_id": 1234,
    "content": "<p>Do you want to save the world? &nbsp;If so, apply today!</p>",
    "internal_content": "<p>Do you want to save the world? &nbsp;If so, apply today!</p>",
    "updated_at": "2016-11-21T15:39:24Z",
    "created_at": "2014-04-01T17:56:19Z",
    "questions": [
        {
            "required": true,
            "private": false,
            "label": "First Name",
            "name": "first_name",
            "type": "short_text",
            "values": [],
            "description": null
        },
        {
            "required": true,
            "private": false,
            "label": "Last Name",
            "name": "last_name",
            "type": "short_text",
            "values": [],
            "description": null
        },
        {
            "required": true,
            "private": false,
            "label": "Email",
            "name": "email",
            "type": "short_text",
            "values": [],
            "description": null
        },
        {
            "required": false,
            "private": false,
            "label": "Phone",
            "name": "phone",
            "type": "short_text",
            "values": [],
            "description": null
        },
        {
            "required": true,
            "private": false,
            "label": "Resume",
            "name": "resume",
            "type": "attachment",
            "values": [],
            "description": null
        },
        {
            "required": false,
            "private": false,
            "label": "Cover Letter",
            "name": "cover_letter",
            "type": "attachment",
            "values": [],
            "description": null
        },
        {
            "required": false,
            "private": false,
            "label": "Have you ever won the lottery?",
            "name": "question_234567",
            "type": "boolean",
            "values": [
                {
                    "value": 0,
                    "label": "No"
                },
                {
                    "value": 1,
                    "label": "Yes"
                }
            ],
            "description": "<p>Please select Yes or No.</p>"
        },
        {
            "required": false,
            "private": true,
            "label": "Do you know what 'the numbers' are?",
            "type": "multi_select",
            "name": "question_345678[]",
            "values": [
                {
                    "value": 862,
                    "label": "Yes"
                },
                {
                    "value": 863,
                    "label": "No"
                },
                {
                    "value": 864,
                    "label": "Maybe"
                }
            ],
            "description": null
        },
        {
            "required": true,
            "private": false,
            "label": "LinkedIn Profile",
            "name": "question_45678",
            "type": "short_text",
            "values": [],
            "description": "<p>Please enter the URL for your LinkedIn profile.</p>"
        },
        {
            "required": true,
            "private": false,
            "label": "How did you hear about this job?",
            "name": "question_56789",
            "type": "short_text",
            "values": [],
            "description": null
        }
    ]
}

Get a single job post.

HTTP Request

GET https://harvest.greenhouse.io/v1/job_posts/{id}


See noteworthy response attributes.

GET: List Job Posts for Job

curl 'https://harvest.greenhouse.io/v1/jobs/{id}/job_posts'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 123,
    "title": "Button Pusher",
    "location": {
      "name": "The Island"
    },
    "internal": true,
    "external": false,
    "active": true,
    "live": true,
    "job_id": 1234,
    "content": "<p>Do you want to save the world? &nbsp;If so, apply today!</p>",
    "internal_content": "<p>Do you want to save the world? &nbsp;If so, apply today!</p>",
    "updated_at": "2016-11-21T15:39:24Z",
    "created_at": "2014-04-01T17:56:19Z",
    "questions": [
      {
        "required": true,
        "private": false,
        "label": "First Name",
        "name": "first_name",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "Last Name",
        "name": "last_name",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "Email",
        "name": "email",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": false,
        "private": false,
        "label": "Phone",
        "name": "phone",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "Resume",
        "name": "resume",
        "type": "attachment",
        "values": [],
        "description": null
      },
      {
        "required": false,
        "private": false,
        "label": "Cover Letter",
        "name": "cover_letter",
        "type": "attachment",
        "values": [],
        "description": null
      },
      {
        "required": false,
        "private": false,
        "label": "Have you ever won the lottery?",
        "name": "question_234567",
        "type": "boolean",
        "values": [
          {
            "value": 0,
            "label": "No"
          },
          {
            "value": 1,
            "label": "Yes"
          }
        ],
        "description": "<p>Please select Yes or No.</p>"
      },
      {
        "required": false,
        "private": true,
        "label": "Do you know what 'the numbers' are?",
        "type": "multi_select",
        "name": "question_345678[]",
        "values": [
          {
            "value": 862,
            "label": "Yes"
          },
          {
            "value": 863,
            "label": "No"
          },
          {
            "value": 864,
            "label": "Maybe"
          }
        ],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "LinkedIn Profile",
        "name": "question_45678",
        "type": "short_text",
        "values": [],
        "description": "<p>Please enter the URL for your LinkedIn profile.</p>"
      },
      {
        "required": true,
        "private": false,
        "label": "How did you hear about this job?",
        "name": "question_56789",
        "type": "short_text",
        "values": [],
        "description": null
      }
    ]
  },
  {
    "id": 129548,
    "live": true,
    "title": "Test job two",
    "location": {
      "name": "Material Plane"
    },
    "internal": false,
    "external": true,
    "job_id": 146218,
    "content": "job post content two",
    "updated_at": "2016-11-21T15:39:24Z",
    "created_at": "2014-04-01T17:56:19Z",
    "internal_content": "",
    "created_at": "2015-11-22T05:49:35.145Z",
    "questions": [
      {
        "required": true,
        "private": false,
        "label": "First Name",
        "name": "first_name",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "Last Name",
        "name": "last_name",
        "type": "short_text",
        "values": [],
        "description": null
      }
    ]
  }
]

List all the corresponding job posts for a given Job ID.

HTTP Request

GET https://harvest.greenhouse.io/v1/jobs/{id}/job_posts

URL parameters

ParameterDescription
idThe ID of the job whose job posts you want to retrieve

Querystring parameters

ParameterDescription
activeIf true, only return active job posts. If false, only return deleted job posts. When omitted, return both active and deleted job posts.


See noteworthy response attributes.

GET: Retrieve Job Post for Job

curl 'https://harvest.greenhouse.io/v1/jobs/{id}/job_post'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

{
    "id": 123,
    "title": "Button Pusher",
    "location": {
      "name": "The Island"
    },
    "internal": true,
    "external": false,
    "active": true,
    "live": true,
    "job_id": 1234,
    "content": "<p>Do you want to save the world? &nbsp;If so, apply today!</p>",
    "internal_content": "<p>Do you want to save the world? &nbsp;If so, apply today!</p>",
    "updated_at": "2016-11-21T15:39:24Z",
    "created_at": "2014-04-01T17:56:19Z",
    "questions": [
      {
        "required": true,
        "private": false,
        "label": "First Name",
        "name": "first_name",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "Last Name",
        "name": "last_name",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "Email",
        "name": "email",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": false,
        "private": false,
        "label": "Phone",
        "name": "phone",
        "type": "short_text",
        "values": [],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "Resume",
        "name": "resume",
        "type": "attachment",
        "values": [],
        "description": null
      },
      {
        "required": false,
        "private": false,
        "label": "Cover Letter",
        "name": "cover_letter",
        "type": "attachment",
        "values": [],
        "description": null
      },
      {
        "required": false,
        "private": false,
        "label": "Have you ever won the lottery?",
        "name": "question_234567",
        "type": "boolean",
        "values": [
          {
            "value": 0,
            "label": "No"
          },
          {
            "value": 1,
            "label": "Yes"
          }
        ],
        "description": "<p>Please select Yes or No.</p>"
      },
      {
        "required": false,
        "private": true,
        "label": "Do you know what 'the numbers' are?",
        "type": "multi_select",
        "name": "question_345678[]",
        "values": [
          {
            "value": 862,
            "label": "Yes"
          },
          {
            "value": 863,
            "label": "No"
          },
          {
            "value": 864,
            "label": "Maybe"
          }
        ],
        "description": null
      },
      {
        "required": true,
        "private": false,
        "label": "LinkedIn Profile",
        "name": "question_45678",
        "type": "short_text",
        "values": [],
        "description": "<p>Please enter the URL for your LinkedIn profile.</p>"
      },
      {
        "required": true,
        "private": false,
        "label": "How did you hear about this job?",
        "name": "question_56789",
        "type": "short_text",
        "values": [],
        "description": null
      }
    ]
  }

Retrieve the corresponding job post for a given Job ID.

HTTP Request

GET https://harvest.greenhouse.io/v1/jobs/{id}/job_post

URL parameters

ParameterDescription
idThe ID of the job whose job post you want to retrieve

Querystring parameters

ParameterDescription
contentIf present, will return the text of the job post as posted to the external job board.
questionsIf present, will return an array of questions associated with this job post.


See noteworthy response attributes.

PATCH: Update Job Post

curl -X PATCH 'https://harvest.greenhouse.io/v1/job_posts/{id}'
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
    "status": "live",
    "title": "New Job Title",
    "location": "NYC",
    "content": "<p style=\"text-align: center;\"><span style=\"font-weight: 400;\">My exciting new job post!</span></p><p>Check it out!</p>"
}

The above returns a JSON response on success:

{
    "success": true
}

Update some properties of a job post.

HTTP Request

PATCH https://harvest.greenhouse.io/v1/job_posts/{id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
statusNostringOne of ‘live’ or 'offline’
titleNostringThe new title for this job post.
locationNostringThe new location for this job post. This is just a plain text string.
contentNostringThe new body of the job post. This will replace the entire existing job post body.

Important Note: Due to JSON restrictions, the HTML body of the new job post should be a single line, with no newline characters and with all double quotes escaped. If your job posts require significant formatting, we recommend using Greenhouse’s job post editor to make changes.

Job Stages

An organization’s job stages.

The job stage object

{
  "id": 72200,
  "name": "Face to Face",
  "interviews": [
    {
      "id": 6001,
      "name": "Cultural Fit Interview",
      "interview_kit": {
        "id": 9123,
        "content": "<h5>Purpose</h5><span>Determine whether or not the candidate would be a strong fit.</span>",
        "questions": [
          {
            "id": 11052,
            "question": "Is this person really a good fit?"
          }
        ]
      }
    },
    {
      "id": 6002,
      "name": "Executive Interview",
      "interview_kit": {
        "id": 9124,
        "content": "<h5>Purpose</h5><span>See if they can work with the boss.</span>",
        "questions": [
          {
            "id": 11053,
            "question": "What's their favorite color?"
          },
          {
            "id": 11054,
            "question": "Do they really want to work here?"
          }
        ]
      }
    }
  ]
}

Noteworthy attributes

AttributeDescription
idThe job stage’s unique identifier
interviewsAn array of interviews associated with this job stage.

GET: List Job Stages

curl 'https://harvest.greenhouse.io/v1/job_stages' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 6001,
    "name": "Cultural Fit Interview",
    "created_at": "2015-11-22T05:31:37.263Z",
    "updated_at": "2015-11-22T05:31:37.263Z",
    "job_id": 12345,
    "interviews": [
      {
        "id": 7890,
        "name": "Cultural Fit Interview",
        "interview_kit": {
          "id": 9124,
          "content": "<h5>Purpose</h5><span>Determine whether or not the candidate would be a strong fit.</span>",
          "questions": [
              {
                "id": 11052,
                "question": "Is this person really a good fit?"
              }
            ]        
          }
        }
      ]
    },
  {
    "id": 6002,
    "name": "Executive Interview",
    "created_at": "2015-11-22T05:31:37.263Z",
    "updated_at": "2015-11-22T05:31:37.263Z",
    "job_id": 34567,
    "interviews": [
      {
        "id": 7345,
        "name": "Executive Interview",
        "interview_kit": {
          "id": 9125,
          "content": "<h5>Purpose</h5><span>Determine whether or not the candidate would be a strong fit.</span>",
          "questions": [
              {
                "id": 11053,
                "question": "What's their favorite color?"
              },
              {
                "id": 11054,
                "question": "Do they really want to work here?"
              }
            ]        
          }
        }
      ]
    }
  ]

List all of an organization’s job stages.

HTTP Request

GET https://harvest.greenhouse.io/v1/job_stages

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
created_beforeReturn only job stages that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_afterReturn only job stages that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_beforeReturn only job stages that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_afterReturn only job stages that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.


See noteworthy response attributes.

GET: List Job Stages for Job

curl 'https://harvest.greenhouse.io/v1/jobs/{id}/stages' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 72200,
    "name": "Face to Face",
    "created_at": "2015-11-22T05:31:37.263Z",
    "updated_at": "2015-11-22T05:31:37.263Z",
    "job_id": 146218,
    "interviews": [
      {
        "id": 6001,
        "name": "Cultural Fit Interview",
        "interview_kit": {
          "id": 9128,
          "content": "<h5>Purpose</h5><span>Determine whether or not the candidate would be a strong fit.</span>",
          "questions": [
            {
              "id": 11052,
              "question": "Is this person really a good fit?"
            }
          ]
        }
      },
      {
        "id": 6002,
        "name": "Executive Interview",
        "created_at": "2015-11-22T05:31:37.263Z",
        "updated_at": "2015-11-22T05:31:37.263Z",
        "job_id": 146219,
        "interview_kit": {
          "id": 9129,
          "content": "<h5>Purpose</h5><span>See if they can work with the boss.</span>",
          "questions": [
            {
              "id": 11053,
              "question": "What's their favorite color?"
            },
            {
              "id": 11054,
              "question": "Do they really want to work here?"
            }
          ]
        }
      }
    ]
  },
  {
    "id": 72199,
    "name": "Offer",
    "created_at": "2015-11-22T05:31:37.263Z",
    "updated_at": "2015-11-22T05:31:37.263Z",
    "job_id": 146220,
    "interviews": []
  },
  {
    "id": 72194,
    "name": "Application Review",
    "created_at": "2015-11-22T05:31:37.263Z",
    "updated_at": "2015-11-22T05:31:37.263Z",
    "job_id": 146221,
    "interviews": [
      {
        "id": 8004,
        "name": "Application Review",
        "interview_kit": {
          "id": 9130,
          "content": null,
          "questions": []
        }
      }
    ]
  }
]

Retrieve the stages for the specified job id.

HTTP Request

GET https://harvest.greenhouse.io/v1/jobs/{id}/stages

URL Parameters

ParameterDescription
idThe ID of the job whose job stages you want to retrieve.

Querystring parameters

ParameterDescription
created_beforeReturn only job stages that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_afterReturn only job stages that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_beforeReturn only job stages that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_afterReturn only job stages that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.


See noteworthy response attributes.

GET: Retrieve Job Stage

curl 'https://harvest.greenhouse.io/v1/job_stages/{id}' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

{
  "id": 6001,
  "name": "Cultural Fit Interview",
  "created_at": "2015-11-22T05:31:37.263Z",
  "updated_at": "2015-11-22T05:31:37.263Z",
  "job_id": 12345,
  "interviews": [
    {
      "id": 7890,
      "name": "Cultural Fit Interview",
      "interview_kit": {
        "id": 9127,
        "content": "<h5>Purpose</h5><span>Determine whether or not the candidate would be a strong fit.</span>",
        "questions": [
            {
              "id": 11052,
              "question": "Is this person really a good fit?"
            }
          ]        
        }
      }
    ]
  }

Retreieve a job stage by its id.

HTTP Request

GET https://harvest.greenhouse.io/v1/job_stages/{id}

URL Parameters

ParameterDescription
idThe ID of the job stage to retrieve


See noteworthy response attributes.

Jobs

The job object

An organization’s jobs.

{
  "id": 6404,
  "name": "Archaeologist",
  "requisition_id": "abc123",
  "notes": "<p>Resistance to electro-magnetic radiation a plus!</p>",
  "confidential": false,
  "status": "closed",
  "created_at": "2013-12-10T14:42:58Z",
  "opened_at": "2013-12-11T14:42:58Z",
  "closed_at": "2013-12-12T14:42:58Z",
  "departments": [
      {
          "id": 25907,
          "name": "Second-Level department",
          "parent_id": 25908,
          "child_ids": [
              14510
          ],
          "external_id": "12345"
      }
  ],
  "offices": [
      {
          "id": 47012,
          "name": "New York",
          "location": {
              "name": "New York, United States"
          },
          "primary_contact_user_id": 150893,
          "parent_id": 50849,
          "child_ids": [
              50852,
              50891
          ],
          "external_id": "15679"
      }
  ],
  "custom_fields": {
    "employment_type": "Full-Time",
    "maximum_budget": "$81.5k",
    "salary_range": {
      "min_value": 70000,
      "max_value": 90000,
      "unit": "USD"
    }
  },
  "keyed_custom_fields": {
    "employment_type": {
      "name": "Time type",
      "type": "single_select",
      "value": "Full-Time"
    },
    "budget": {
      "name": "Maximum Budget",
      "type": "short_text",
      "value": "Full-Time"
    },
    "salary_range": {
      "name": "Salary Range",
      "type": "currency_range",
      "value": {
        "min_value": 70000,
        "max_value": 90000,
        "unit": "USD"
      }
    }
  },
  "hiring_team": {
    "hiring_managers": [
      {
        "id": 84275,
        "first_name": "Kaylee",
        "last_name": "Prime",
        "name": "Kaylee Prime",
        "employee_id": "13636"
      },
      {
        "id": 169779,
        "first_name": "Hank",
        "last_name": "Hollandaise",
        "name": "Hank Hollandaise",
        "employee_id": "34537"
      }
    ],
    "recruiters": [
      {
        "id": 81111,
        "first_name": "Samuel",
        "last_name": "Skateboard",
        "name": "Samuel Skateboard",
        "employee_id": "34531",
        "responsible": false
      },
      {
        "id": 153448,
        "first_name": "Stegosaurus",
        "last_name": "Heels",
        "name": "Stegosaurus Heels",
        "employee_id": "45748",
        "responsible": true
      }
    ],
    "coordinators": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327",
        "responsible": true
      },
      {
        "id": 177046,
        "first_name": "Mirandella",
        "last_name": "Lager",
        "name": "Mirandella Lager",
        "employee_id": "43626",
        "responsible": false
      }
    ],
    "sourcers": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327"
      }
    ]
  },
  "openings": [
    {
      "id": 123,
      "opening_id": "3-1",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.736Z",
      "closed_at": "2017-11-20T23:14:14.736Z",
      "application_id": 45678,
      "close_reason": {
        "id": 678,
        "name": "Hired - Backfill"
      }
    },
    {
      "id": 124,
      "opening_id": "3-2",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.739Z",
      "closed_at": null,
      "application_id": null,
      "close_reason": null
    },
    {
      "id": 125,
      "opening_id": null,
      "status": "open",
      "opened_at": "2016-02-03T20:00:00.000Z",
      "closed_at": null,
      "application_id": null
    },
    {
      "id": 126,
      "opening_id": "2-4",
      "status": "closed",
      "opened_at": "2016-02-03T16:38:46.985Z",
      "closed_at": "2016-02-03T16:39:09.811Z",
      "application_id": 1232,
      "close_reason": {
        "id": 689,
        "name": "Hired"
      }
    }
  ]
}

Noteworthy attributes

AttributeDescription
idThe job’s unique identifier
requisition_idAn arbitrary ID provided by an external source; does not map to another entity within Greenhouse.
statusOne of open, closed, draft.
confidentialOne of true, false. If the job is confidential or not.
departmentsAn array containing the department which this job belongs to.
officesAn array containing the offices this job is associated with.
hiring_teamLists the names and User IDs of the hiring managers, recruiters, coordinators and sourcers associated with this job. For recruiters and coordinators, there is a responsible boolean flag which indicates that the user is the responsible recruiter or coordinator for this job.
custom_fieldsContains any custom job fields which have been defined by your organization.
keyed_custom_fieldsThis contains the same information as custom_fields but formatted in a different way that includes more information. This will tell you the type of custom field data to expect, the text name of custom field, and the value. The key of this hash is the custom field’s immutable field key, which will not change even if the name of the custom field is changed in Greenhouse.
openingsLists the openings associated with this job.
openings[].opening_idCustom identifier set by an organization. Can be null.
openings[].statusOne of: ["open", "closed"]
openings[].opened_atTimestamp when the opening was created.
openings[].closed_atTimestamp when the opening was closed. An opening is closed when it is filled or removed.
openings[].application_idIf the opening is closed and a candidate was hired to fill the opening, this is the ID of the candidate’s application. Otherwise, null.
openings[].close_reasonIf the opening is closed, it may or may not have a reason for the closure. This contains the id and name of the close reason.

GET: List Jobs

curl 'https://harvest.greenhouse.io/v1/jobs'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns a JSON response, structured like this:

[
  {
  "id": 6404,
  "name": "Archaeologist",
  "requisition_id": "abc123",
  "notes": "<p>Resistance to electro-magnetic radiation a plus!</p>",
  "confidential": false,
  "status": "closed",
  "created_at": "2013-12-10T14:42:58Z",
  "opened_at": "2013-12-11T14:42:58Z",
  "closed_at": "2013-12-12T14:42:58Z",
  "departments": [
      {
          "id": 25907,
          "name": "Second-Level department",
          "parent_id": 25908,
          "child_ids": [
              14510
          ],
          "external_id": "12345"
      }
  ],
  "offices": [
      {
          "id": 47012,
          "name": "New York",
          "location": {
              "name": "New York, United States"
          },
          "primary_contact_user_id": 150893,
          "parent_id": 50849,
          "child_ids": [
              50852,
              50891
          ],
          "external_id": "15679"
      }
  ],
  "custom_fields": {
    "employment_type": "Full-Time",
    "maximum_budget": "$81.5k",
    "salary_range": {
      "min_value": 70000,
      "max_value": 90000,
      "unit": "USD"
    }
  },
  "keyed_custom_fields": {
    "employment_type": {
      "name": "Time type",
      "type": "single_select",
      "value": "Full-Time"
    },
    "budget": {
      "name": "Maximum Budget",
      "type": "short_text",
      "value": "Full-Time"
    },
    "salary_range": {
      "name": "Salary Range",
      "type": "currency_range",
      "value": {
        "min_value": 70000,
        "max_value": 90000,
        "unit": "USD"
      }
    }
  },
  "hiring_team": {
    "hiring_managers": [
      {
        "id": 84275,
        "first_name": "Kaylee",
        "last_name": "Prime",
        "name": "Kaylee Prime",
        "employee_id": "13636"
      },
      {
        "id": 169779,
        "first_name": "Hank",
        "last_name": "Hollandaise",
        "name": "Hank Hollandaise",
        "employee_id": "34537"
      }
    ],
    "recruiters": [
      {
        "id": 81111,
        "first_name": "Samuel",
        "last_name": "Skateboard",
        "name": "Samuel Skateboard",
        "employee_id": "34531",
        "responsible": false
      },
      {
        "id": 153448,
        "first_name": "Stegosaurus",
        "last_name": "Heels",
        "name": "Stegosaurus Heels",
        "employee_id": "45748",
        "responsible": true
      }
    ],
    "coordinators": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327",
        "responsible": true
      },
      {
        "id": 177046,
        "first_name": "Mirandella",
        "last_name": "Lager",
        "name": "Mirandella Lager",
        "employee_id": "43626",
        "responsible": false
      }
    ],
    "sourcers": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327"
      }
    ]
  },
  "openings": [
    {
      "id": 123,
      "opening_id": "3-1",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.736Z",
      "closed_at": "2017-11-20T23:14:14.736Z",
      "application_id": 45678,
      "close_reason": {
        "id": 678,
        "name": "Hired - Backfill"
      }
    },
    {
      "id": 124,
      "opening_id": "3-2",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.739Z",
      "closed_at": null,
      "application_id": null,
      "close_reason": null
    },
    {
      "id": 125,
      "opening_id": null,
      "status": "open",
      "opened_at": "2016-02-03T20:00:00.000Z",
      "closed_at": null,
      "application_id": null
    },
    {
      "id": 126,
      "opening_id": "2-4",
      "status": "closed",
      "opened_at": "2016-02-03T16:38:46.985Z",
      "closed_at": "2016-02-03T16:39:09.811Z",
      "application_id": 1232,
      "close_reason": {
        "id": 689,
        "name": "Hired"
      }
    }
  ]
}
]

List all of an organization’s jobs.

HTTP Request

GET https://harvest.greenhouse.io/v1/jobs

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
created_beforeReturn only jobs that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_afterReturn only jobs that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_beforeReturn only jobs that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_afterReturn only jobs that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.
requisition_idIf included, will return only the jobs that match the given requisition_id
opening_idIf included, will return only the jobs that contain at least one opening with the given opening_id.
statusOne of ‘open’, 'closed’, or 'draft’. If included, will only return jobs with that status.
department_idIf included, will return only the jobs in this specific department.
external_department_idThis may be used instead of department_id and represents the ID of the department in an external system.
office_idIf included, will return only the jobs in this specific office.
external_office_idThis may be used instead of office_id and represents the ID of the office in an external system.
custom_field_option_idThe job contains a custom field with this custom_field_option_id selected. Option IDs can be retrieved from the GET Custom Field Options endpoint.


See noteworthy response attributes.

GET: Retrieve Job

curl 'https://harvest.greenhouse.io/v1/jobs/{id}'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns a JSON response, structured like this:

{
  "id": 6404,
  "name": "Archaeologist",
  "requisition_id": "abc123",
  "notes": "<p>Resistance to electro-magnetic radiation a plus!</p>",
  "confidential": false,
  "status": "closed",
  "created_at": "2013-12-10T14:42:58Z",
  "opened_at": "2013-12-11T14:42:58Z",
  "closed_at": "2013-12-12T14:42:58Z",
  "departments": [
      {
          "id": 25907,
          "name": "Second-Level department",
          "parent_id": 25908,
          "child_ids": [
              14510
          ],
          "external_id": "12345"
      }
  ],
  "offices": [
      {
          "id": 47012,
          "name": "New York",
          "location": {
              "name": "New York, United States"
          },
          "primary_contact_user_id": 150893,
          "parent_id": 50849,
          "child_ids": [
              50852,
              50891
          ],
          "external_id": "15679"
      }
  ],
  "custom_fields": {
    "employment_type": "Full-Time",
    "maximum_budget": "$81.5k",
    "salary_range": {
      "min_value": 70000,
      "max_value": 90000,
      "unit": "USD"
    }
  },
  "keyed_custom_fields": {
    "employment_type": {
      "name": "Time type",
      "type": "single_select",
      "value": "Full-Time"
    },
    "budget": {
      "name": "Maximum Budget",
      "type": "short_text",
      "value": "Full-Time"
    },
    "salary_range": {
      "name": "Salary Range",
      "type": "currency_range",
      "value": {
        "min_value": 70000,
        "max_value": 90000,
        "unit": "USD"
      }
    }
  },
  "hiring_team": {
    "hiring_managers": [
      {
        "id": 84275,
        "first_name": "Kaylee",
        "last_name": "Prime",
        "name": "Kaylee Prime",
        "employee_id": "13636"
      },
      {
        "id": 169779,
        "first_name": "Hank",
        "last_name": "Hollandaise",
        "name": "Hank Hollandaise",
        "employee_id": "34537"
      }
    ],
    "recruiters": [
      {
        "id": 81111,
        "first_name": "Samuel",
        "last_name": "Skateboard",
        "name": "Samuel Skateboard",
        "employee_id": "34531",
        "responsible": false
      },
      {
        "id": 153448,
        "first_name": "Stegosaurus",
        "last_name": "Heels",
        "name": "Stegosaurus Heels",
        "employee_id": "45748",
        "responsible": true
      }
    ],
    "coordinators": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327",
        "responsible": true
      },
      {
        "id": 177046,
        "first_name": "Mirandella",
        "last_name": "Lager",
        "name": "Mirandella Lager",
        "employee_id": "43626",
        "responsible": false
      }
    ],
    "sourcers": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327"
      }
    ]
  },
  "openings": [
    {
      "id": 123,
      "opening_id": "3-1",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.736Z",
      "closed_at": "2017-11-20T23:14:14.736Z",
      "application_id": 45678,
      "close_reason": {
        "id": 678,
        "name": "Hired - Backfill"
      }
    },
    {
      "id": 124,
      "opening_id": "3-2",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.739Z",
      "closed_at": null,
      "application_id": null,
      "close_reason": null
    },
    {
      "id": 125,
      "opening_id": null,
      "status": "open",
      "opened_at": "2016-02-03T20:00:00.000Z",
      "closed_at": null,
      "application_id": null
    },
    {
      "id": 126,
      "opening_id": "2-4",
      "status": "closed",
      "opened_at": "2016-02-03T16:38:46.985Z",
      "closed_at": "2016-02-03T16:39:09.811Z",
      "application_id": 1232,
      "close_reason": {
        "id": 689,
        "name": "Hired"
      }
    }
  ]
}

HTTP Request

GET https://harvest.greenhouse.io/v1/jobs/{id}

URL Parameters

ParameterDescription
idThe ID of the job to retrieve


See noteworthy response attributes.

PATCH: Update Job

curl -X PATCH 'https://harvest.greenhouse.io/v1/jobs/{id}'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
   "name": "New job name",
   "requisition_id": "1",
   "notes": "Here are some notes",
   "team_and_responsibilities": "Info",
   "how_to_sell_this_job": "the snacks",
   "office_ids": [1556],
   "external_office_ids": ["office-1"],
   "department_id": 74,
   "external_department_id": "dept-1",
   "custom_fields": [
    {
        "id": 1234,
        "value": "Some new value"
    },
    {
        "name_key": "salary_range",
        "min_value": 100000,
        "max_value": 150000,
        "unit": "USD"
   },
   {
        "id": 5678,
        "delete_value": "true"
   }
  ]
}

The above command returns a JSON response, structured like this:

{
  "id": 6404,
  "name": "New job name",
  "requisition_id": "1",
  "notes": "Here are some notes",
  "confidential": false,
  "status": "closed",
  "created_at": "2013-12-10T14:42:58Z",
  "opened_at": "2013-12-11T14:42:58Z",
  "closed_at": "2013-12-12T14:42:58Z",
  "departments": [
      {
          "id": 74,
          "name": "Second-Level department",
          "parent_id": 25908,
          "child_ids": [
              14510
          ],
          "external_id": "dept-1"
      }
  ],
  "offices": [
      {
          "id": 1556,
          "name": "San Francisco",
          "location": {
              "name": "San Francisco, United States"
          },
          "primary_contact_user_id": 150893,
          "parent_id": 50849,
          "child_ids": [
              50852,
              50891
          ],
          "external_id": "office-1"
      }
  ],
  "custom_fields": {
    "employment_type": "Full-Time",
    "maximum_budget": "$81.5k",
    "salary_range": {
      "min_value": 70000,
      "max_value": 90000,
      "unit": "USD"
    }
  },
  "keyed_custom_fields": {
    "employment_type": {
      "name": "Time type",
      "type": "single_select",
      "value": "Full-Time"
    },
    "budget": {
      "name": "Maximum Budget",
      "type": "short_text",
      "value": "Full-Time"
    },
    "salary_range": {
      "name": "Salary Range",
      "type": "currency_range",
      "value": {
        "min_value": 70000,
        "max_value": 90000,
        "unit": "USD"
      }
    }
  },
  "hiring_team": {
    "hiring_managers": [
      {
        "id": 84275,
        "first_name": "Kaylee",
        "last_name": "Prime",
        "name": "Kaylee Prime",
        "employee_id": "13636"
      },
      {
        "id": 169779,
        "first_name": "Hank",
        "last_name": "Hollandaise",
        "name": "Hank Hollandaise",
        "employee_id": "34537"
      }
    ],
    "recruiters": [
      {
        "id": 81111,
        "first_name": "Samuel",
        "last_name": "Skateboard",
        "name": "Samuel Skateboard",
        "employee_id": "34531",
        "responsible": false
      },
      {
        "id": 153448,
        "first_name": "Stegosaurus",
        "last_name": "Heels",
        "name": "Stegosaurus Heels",
        "employee_id": "45748",
        "responsible": true
      }
    ],
    "coordinators": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327",
        "responsible": true
      },
      {
        "id": 177046,
        "first_name": "Mirandella",
        "last_name": "Lager",
        "name": "Mirandella Lager",
        "employee_id": "43626",
        "responsible": false
      }
    ],
    "sourcers": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327"
      }
    ]
  },
  "openings": [
    {
      "id": 123,
      "opening_id": "3-1",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.736Z",
      "closed_at": "2017-11-20T23:14:14.736Z",
      "application_id": 45678,
      "close_reason": {
        "id": 678,
        "name": "Hired - Backfill"
      }
    },
    {
      "id": 124,
      "opening_id": "3-2",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.739Z",
      "closed_at": null,
      "application_id": null,
      "close_reason": null
    },
    {
      "id": 125,
      "opening_id": null,
      "status": "open",
      "opened_at": "2016-02-03T20:00:00.000Z",
      "closed_at": null,
      "application_id": null
    },
    {
      "id": 126,
      "opening_id": "2-4",
      "status": "closed",
      "opened_at": "2016-02-03T16:38:46.985Z",
      "closed_at": "2016-02-03T16:39:09.811Z",
      "application_id": 1232,
      "close_reason": {
        "id": 689,
        "name": "Hired"
      }
    }
  ]
}

HTTP Request

PATCH https://harvest.greenhouse.io/v1/jobs/{id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

URL Parameters

ParameterDescription
idThe ID of the job to retrieve

JSON Body Parameters

ParameterRequiredTypeDescription
nameNostringThe job’s name
notesNostringNotes on the hiring plan
anywhereNobooleanBoolean value indicating where the job can be done anywhere
requisition_id*NostringThe id of the requisition corresponding to this job posting, if applicable
team_and_responsibilitiesNostringA description of the team the candidate would join and their responsibilities
how_to_sell_this_jobNostringA description for the recruiter of the desirable aspects of the job
custom_fieldsNocustom_fieldArray of hashes containing new custom field values. Passing an empty array does nothing.
office_idsNoArrayReplace the current offices for this job with new offices. If your organization requires at least one office, trying to set this to blank will return an error.
external_office_idsNoArrayThis may be used instead of office_ids and represents the ID of the office in an external system. If this is used, office_id must be blank and vice versa.
department_id*NonumberReplace the current department for this job with a different department.
external_department_id*NostringThis may be used instead of department_id and represents the ID of the department in an external system. If used, department_id must be blank and vice versa.

Custom Field Parameters

The custom field parameter structure is different in the PATCH method then in GET methods and responses. Certain type of custom fields require different elements to be included, while deleting a field requires a specific argument. What follows is the description of each item in a custom field element and what is required depending on the type.

ParameterRequired forDescription
idallThe custom field id for this particular custom field. One of this or name_key is required.
name_keyallThe field key for this custom field. This can be found in Greenhouse while editing custom options as “Immutable Field Key” This or id is required for all custom field elements.
valueallThe value field contains the new custom field value. In most cases this will be a string or a number. In the case of single-select or multi-select custom fields, this will be a custom field option id or an array of custom field option ids, respectively. Value is only not used for range type custom fields.
min_valuenumber_range, currency rangeThis contains the minimum value that is allowable for this custom field. Must be less than max_value
max_valuenumber_range, currency_rangeThis contains the maximum value that is allowable for this custom field. Must be greater than min_value
unitcurrency, currency_rangeThis contains the currency unit for a currency custom field. It is only required when updating a currency custom field. This should accept any 3-character currency code from the ISO-4217 standard.
delete_valuen/aWhen this element is included with a value of “true” (note, string true, not boolean true) the custom field value will be removed from Greenhouse. Note that updating a custom field value to nil or a blank string will not work, as validations require these to be non-blank values.

The above command returns a JSON response, structured like this:

{
  "id": 112746,
  "name": "new name",
  "requisition_id": 2,
  "notes": "Looking for the best!",
  "confidential": false,
  "status": "open",
  "created_at": "2015-09-10T19:01:46.078Z",
  "opened_at": "2015-09-10T19:01:46.078Z",
  "closed_at": null,
  "departments": [
    {
      "id": 74,
      "name": "Guideshops",
      "parent_id": null,
      "child_ids": [],
      "external_id": "EXTERNAL_ID_1234"
    }
  ],
  "offices": [
    {
      "id": 1556,
      "name": "San Diego",
      "location": {
        "name": "San Diego, CA, United States"
      },
      "primary_contact_user_id": 12345,
      "parent_id": null,
      "child_ids": [],
      "external_id": "ABC456"
    }
  ],
  "hiring_team": {
    "hiring_managers": [
      {
        "id": 84275,
        "first_name": "Kaylee",
        "last_name": "Prime",
        "name": "Kaylee Prime",
        "employee_id": "13636"
      },
      {
        "id": 169779,
        "first_name": "Hank",
        "last_name": "Hollandaise",
        "name": "Hank Hollandaise",
        "employee_id": "34537"
      }
    ],
    "recruiters": [
      {
        "id": 81111,
        "first_name": "Samuel",
        "last_name": "Skateboard",
        "name": "Samuel Skateboard",
        "employee_id": "34531",
        "responsible": false
      },
      {
        "id": 153448,
        "first_name": "Stegosaurus",
        "last_name": "Heels",
        "name": "Stegosaurus Heels",
        "employee_id": "45748",
        "responsible": true
      }
    ],
    "coordinators": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327",
        "responsible": true
      },
      {
        "id": 177046,
        "first_name": "Mirandella",
        "last_name": "Lager",
        "name": "Mirandella Lager",
        "employee_id": "43626",
        "responsible": false
      }
    ],
    "sourcers": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327"
      }
    ]
  },
  "openings": [
    {
      "id": 123,
      "opening_id": "3-1",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.736Z",
      "closed_at": "2017-11-20T23:14:14.736Z",
      "application_id": 45678,
      "close_reason": {
        "id": 678,
        "name": "Hired - Backfill"
      }
    },
    {
      "id": 124,
      "opening_id": "3-2",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.739Z",
      "closed_at": null,
      "application_id": null,
      "close_reason": null
    },
    {
      "id": 125,
      "opening_id": null,
      "status": "open",
      "opened_at": "2016-02-03T20:00:00.000Z",
      "closed_at": null,
      "application_id": null
    },
    {
      "id": 126,
      "opening_id": "2-4",
      "status": "closed",
      "opened_at": "2016-02-03T16:38:46.985Z",
      "closed_at": "2016-02-03T16:39:09.811Z",
      "application_id": 1232,
      "close_reason": {
        "id": 689,
        "name": "Hired"
      }
    }
  ]
}


See noteworthy response attributes.

POST: Create Job

curl -X POST 'https://harvest.greenhouse.io/v1/jobs'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
   "template_job_id": 12345,
   "number_of_openings": 2,
   "job_post_name": "External Name That Appears On Job Boards",
   "job_name": "Internal Name That Appears On Hiring Plans",
   "department_id": 123,
   "office_ids": [
      234,
      345
    ],
   "requisition_id": "abc-123",
   "opening_ids": [
      "abc-123-1",
      "abc-123-2"
    ]
}

The above command returns a JSON response, structured like this:

{
  "id": 112746,
  "name": "Internal Name That Appears On Hiring Plans",
  "requisition_id": "abc-123",
  "notes": "Looking for the best!",
  "confidential": false,
  "status": "open",
  "created_at": "2015-09-10T19:01:46.078Z",
  "opened_at": "2015-09-10T19:01:46.078Z",
  "closed_at": null,
  "departments": [
    {
      "id": 123,
      "name": "Guideshops",
      "parent_id": null,
      "child_ids": [
        52461,
        34065,
        25908
      ],
      "external_id": "EXTERNAL_ID_1234"
    }
  ],
  "offices": [
    {
      "id": 234,
      "name": "San Diego",
      "location": {
        "name": "San Diego, CA, United States"
      },
      "primary_contact_user_id": 25463,
      "parent_id": 50850,
      "child_ids": [
        24719    
      ],
      "external_id": "abc13425"
    },
    {
      "id": 345,
      "name": "New York",
      "location": {
        "name": "New York, NY, United States"
      },
      "parent_id": null,
      "child_ids": [],
      "external_id": "13432"
    }
  ],
   "hiring_team": {
    "hiring_managers": [
      {
        "id": 84275,
        "first_name": "Kaylee",
        "last_name": "Prime",
        "name": "Kaylee Prime",
        "employee_id": "13636"
      },
      {
        "id": 169779,
        "first_name": "Hank",
        "last_name": "Hollandaise",
        "name": "Hank Hollandaise",
        "employee_id": "34537"
      }
    ],
    "recruiters": [
      {
        "id": 81111,
        "first_name": "Samuel",
        "last_name": "Skateboard",
        "name": "Samuel Skateboard",
        "employee_id": "34531",
        "responsible": false
      },
      {
        "id": 153448,
        "first_name": "Stegosaurus",
        "last_name": "Heels",
        "name": "Stegosaurus Heels",
        "employee_id": "45748",
        "responsible": true
      }
    ],
    "coordinators": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327",
        "responsible": true
      },
      {
        "id": 177046,
        "first_name": "Mirandella",
        "last_name": "Lager",
        "name": "Mirandella Lager",
        "employee_id": "43626",
        "responsible": false
      }
    ],
    "sourcers": [
      {
        "id": 122635,
        "first_name": "Teddy",
        "last_name": "Pizzazz",
        "name": "Teddy Pizzazz",
        "employee_id": "47327"
      }
    ]
  },
  "openings": [
    {
      "id": 123,
      "opening_id": "3-1",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.736Z",
      "closed_at": "2017-11-20T23:14:14.736Z",
      "application_id": 45678,
      "close_reason": {
        "id": 678,
        "name": "Hired - Backfill"
      }
    },
    {
      "id": 124,
      "opening_id": "3-2",
      "status": "open",
      "opened_at": "2015-11-20T23:14:14.739Z",
      "closed_at": null,
      "application_id": null,
      "close_reason": null
    },
    {
      "id": 125,
      "opening_id": null,
      "status": "open",
      "opened_at": "2016-02-03T20:00:00.000Z",
      "closed_at": null,
      "application_id": null
    },
    {
      "id": 126,
      "opening_id": "2-4",
      "status": "closed",
      "opened_at": "2016-02-03T16:38:46.985Z",
      "closed_at": "2016-02-03T16:39:09.811Z",
      "application_id": 1232,
      "close_reason": {
        "id": 689,
        "name": "Hired"
      }
    }
  ]
}

HTTP Request

POST https://harvest.greenhouse.io/v1/jobs

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
template_job_idYesNumberThis is the job we will use to generate the new job. The new job will receive most of the settings of the template job. The On-Behalf-Of user must have access to this job.
number_of_openingsYesNumberThe number of openings that will be created for this job.
job_post_nameNoStringThis will be the name on the new job post. If this is not included, the job post names in the base job will be copied.
job_nameNoStringThis is the internal name of the new job. If this is not included, the name of the new job will be “Copy Of (the template job’s name)”
department_idNoNumberThe department of the new job. This should be a department id from the Departments endpoint. If this element is omitted, the new job will receive the department of the template job. If this element is included but blank, it will create the job with no departments. If the organization requires jobs to have a department, this case will return a 422 response.
external_department_idNoStringThis may be used instead of department_id and represents the ID of the department in an external system. If this is used, department_id must be blank and vice versa.
office_idsNoArray[Numbers]The offices of the new job. These should be office ids from the Offices endpoint. If this element is omitted, the new job will receive the offices of the template job. If this element is included but blank, it will create the job with no offices. If the organization requires jobs to have an office, this case will return a 422 response.
external_office_idsNoArray[Srings]This may be used instead of office_ids and represents the IDs of the offices in an external system. If this is used, office_ids must be blank and vice versa.
requisition_idNoStringA requisition id for this job.
opening_idsNoArray[Strings]An array of opening ids for the new job. If this is included, the number of opening ids in this array must match the number_of_openings element.

GET: Hiring Team

curl 'https://harvest.greenhouse.io/v1/jobs/{id}/hiring_team'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns a JSON response, structured like this:

{
    "hiring_managers": [
        {"user_id": 11, "active": true},
        {"user_id": 12, "active": false}
    ],
    "recruiters": [
        {"user_id": 13, "active": false, "responsible": false},
        {"user_id": 14, "active": true, "responsible": false},
        {"user_id": 15, "active": true, "responsible": true}
    ],
    "coordinators": [
        {"user_id": 16, "active": false, "responsible": false},
        {"user_id": 17, "active": true, "responsible": false},
        {"user_id": 18, "active": true, "responsible": true}
    ],
    "sourcers": [
        {"user_id": 19, "active": true},
        {"user_id": 20, "active": false}
    ]
}

HTTP Request

GET https://harvest.greenhouse.io/v1/jobs/{id}/hiring_team

URL Parameters

ParameterDescription
idThe ID of the job to retrieve

Notable Response Parameters

ParameterTypeDescription
activebooleanThis flag informs you if the user still has access to the job in question. In the case where a former hiring team member loses permission to the job, that member may still have historical information related to the job so the relationship is maintained.
responsiblebooleanThis flag only exists for recruiters or coordinators and tells you if the team member has been designated as the “responsible” member for future candidates on the job. This is analogous to the “responsible_for_future_candidates” field on the PUT hiring team endpoint. It is unrelated to active or inactive candidates, which trigger an in the moment migration and are not stored on the hiring team.


PUT: Replace Hiring Team

curl -X PUT 'https://harvest.greenhouse.io/v1/jobs/{id}'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "hiring_managers": [
    {
      "user_id": 1234
    },
    {
      "user_id": 2345
    }
  ],
  "sourcers": [
    {
      "user_id": 3456
    },
    {
      "user_id": 4567
    }
  ],
  "recruiters": [
    {
      "user_id": 5678,
      "responsible_for_future_candidates": true,
      "responsible_for_active_candidates": true,
      "responsible_for_inactive_candidates": true
    },
    {
      "user_id": 6789,
      "responsible_for_future_candidates": false,
      "responsible_for_active_candidates": false,
      "responsible_for_inactive_candidates": false
    }
  ],
  "coordinators": [
    {
      "user_id": 7890,
      "responsible_for_future_candidates": true,
      "responsible_for_active_candidates": false,
      "responsible_for_inactive_candidates": false
    },
    {
      "user_id": 8901,
      "responsible_for_future_candidates": false,
      "responsible_for_active_candidates": false,
      "responsible_for_inactive_candidates": false
    }
  ]
}

The above command returns a JSON response, structured like this:

{
    "success": true
}

HTTP Request

PUT https://harvest.greenhouse.io/v1/jobs/{id}/hiring_team

JSON Body Parameters

There are four types of hiring team members, represented by the four hashes sent in the JSON body. If any of these types are not included, hiring team members of that type will not be changed. If a blank element {} is included, that part of the hiring team will be cleared.

Note that this PUT method REPLACES the existing members of the hiring team. For each element included in the JSON request body, the existing hiring team members in Greenhouse will be removed and replaced with the current members. This includes the removal of disabled and inactive users, who can never be re-added. For more granular control over additions and removals, use the POST or DELETE methods on this endpoint. Also, this process is transactional: if there is one failure, no elements will be updated. Finally, if you have a Hiring Team Updated web hook configured, you will receive one web hook notification per element, so you may receive up to four web hook notifications when this endpoint is used.

ParameterRequiredTypeDescription
responsible_for_future_candidatesYes for coordinator or recruiterbooleanThe user becomes the responsible person for all new candidates. Only one user in the group of users may be designated as responsible.
responsible_for_active_candidatesYes for coordinator or recruiterbooleanThe user becomes the responsible person for all existing candidates with active applications
responsible_for_inactive_candidatesYes for coordinator or recruiterbooleanThe user becomes the responsible person for all hired and rejected candidates

On success, this will return a 200 response code with a success message in the JSON body.

POST: Add Hiring Team Members

curl -X POST 'https://harvest.greenhouse.io/v1/jobs/{id}'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "hiring_managers": [
    {
      "user_id": 1234
    },
    {
      "user_id": 2345
    }
  ],
  "sourcers": [
    {
      "user_id": 3456
    },
    {
      "user_id": 4567
    }
  ],
  "recruiters": [
    {
      "user_id": 5678,
      "responsible_for_future_candidates": true,
      "responsible_for_active_candidates": true,
      "responsible_for_inactive_candidates": true
    },
    {
      "user_id": 6789,
      "responsible_for_future_candidates": false,
      "responsible_for_active_candidates": false,
      "responsible_for_inactive_candidates": false
    }
  ],
  "coordinators": [
    {
      "user_id": 7890,
      "responsible_for_future_candidates": true,
      "responsible_for_active_candidates": false,
      "responsible_for_inactive_candidates": false
    },
    {
      "user_id": 8901,
      "responsible_for_future_candidates": false,
      "responsible_for_active_candidates": false,
      "responsible_for_inactive_candidates": false
    }
  ]
}

The above command returns a JSON response, structured like this:

{
    "success": true
}

HTTP Request

POST https://harvest.greenhouse.io/v1/jobs/{id}/hiring_team

JSON Body Parameters

This method adds new hiring team members. If a user is designated as “responsible_for_future_candites” and a responsible user already exists, the new user will become the responsible user and the old user will no longer be responsible. This endpoint is transactional, if any items fail to add, the entire request will fail and no changes will be made. Finally, if you have a Hiring Team Updated web hook configured, you will receive one web hook notification per element, so you may receive up to four web hook notifications when this endpoint is used.

ParameterRequiredTypeDescription
responsible_for_future_candidatesYes for coordinator or recruiterbooleanThe user becomes the responsible person for all new candidates. Only one user in the group of users may be designated as responsible.
responsible_for_active_candidatesYes for coordinator or recruiterbooleanThe user becomes the responsible person for all existing candidates with active applications
responsible_for_inactive_candidatesYes for coordinator or recruiterbooleanThe user becomes the responsible person for all hired and rejected candidates

On success, this will return a 200 response code with a success message in the JSON body.

DELETE: Remove Hiring Team Member

curl -X DELETE 'https://harvest.greenhouse.io/v1/jobs/{id}'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "hiring_managers": [1234, 2345],
  "sourcers": [3456, 4567],
  "recruiters": [5678, 6789],
  "coordinators": [7890, 8901]
}

The above command returns a JSON response, structured like this:

{
    "success": true
}

HTTP Request

DELETE https://harvest.greenhouse.io/v1/jobs/{id}/hiring_team

JSON Body Parameters

This method removes hiring team members with the designated user ids from the designated type. If a user id is provided that does not exist in the hiring team of that type, it will be ignored and no error will be raised. Disabled and inactive users can be removed with this endpoint, but you will be unable to re-add them. If you have a Hiring Team Updated web hook configured, you will receive one web hook notification per element, so you may receive up to four web hook notifications when this endpoint is used.

On success, this will return a 200 response code with a success message in the JSON body.

Offers

The offer object

An organization’s offers.

{
  "id": 1142785,
  "version": 1,
  "application_id": 91081818,
  "job_id": 84593,
  "candidate_id": 7328851,
  "created_at": "2018-06-06T20:23:10.378Z",
  "updated_at": "2018-06-06T20:23:43.388Z",
  "sent_at": "2018-06-07",
  "resolved_at": "2018-06-06T20:23:43.387Z",
  "starts_at": "2018-07-20",
  "status": "accepted",
  "custom_fields": {
    "employment_type": "Contractor",
    "favorite_station": "The Swan",
    "best_seasons": null,
    "start_date": "2004-09-21",
    "willing_to_negotiate": null,
    "salary": "Around $100k",
    "notes": "This is a note field"
  },
  "keyed_custom_fields": {
    "time_type": {
      "name": "Employment Type",
      "type": "single_select",
      "value": "Contractor"
    },
    "favorite_station": {
      "name": "Favorite Station",
      "type": "single_select",
      "value": "The Swan"
    },
    "best_seasons": {
      "name": "Best seasons",
      "type": "multi_select",
      "value": null
    },
    "start_date": {
      "name": "Start Date",
      "type": "date",
      "value": "2004-09-21"
    },
    "will_negotiate": {
      "name": "Willing to negotiate",
      "type": "yes_no",
      "value": null
    },
    "salary": {
      "name": "Salary",
      "type": "short_text",
      "value": "Around $100k"
    },
    "notes": {
      "name": "Notes",
      "type": "long_text",
      "value": "This is a note field"
    }
  }
}

Noteworthy attributes

AttributeDescription
idThe offer’s unique identifier
versionThe version number of this offer. When an existing offer is updated, a new one is typically created with an incremented version.
application_idThe ID of the associated application.
created_atDate whe this offer was created.
resolved_atDate when this offer was resolved (e.g. when it was accepted, rejected).
sent_atDate when this offer was sent to the candidate.
starts_atDate when the candidate starts. This is the date value entered in the default Start Date field on candidate’s Offer Details. This is the first field on their Offer Details, above the custom fields.
statusOne of: unresolved, accepted, rejected, deprecated.
custom_fieldsContains a hash of the custom fields configured for this resource. The properties in this hash reflect the active custom fields as of the time this method is called.
keyed_custom_fieldsThis contains the same information as custom_fields but formatted in a different way that includes more information. This will tell you the type of custom field data to expect, the text name of custom field, and the value. The key of this hash is the custom field’s immutable field key, which will not change even if the name of the custom field is changed in Greenhouse.

GET: List Offers

All offers made by an organization ordered by application_id.

curl 'https://harvest.greenhouse.io/v1/offers' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
[
  {
  "id": 1142785,
  "version": 1,
  "application_id": 91081818,
  "job_id": 84593,
  "candidate_id": 7328851,
  "created_at": "2018-06-06T20:23:10.378Z",
  "updated_at": "2018-06-06T20:23:43.388Z",
  "sent_at": "2018-06-07",
  "resolved_at": "2018-06-06T20:23:43.387Z",
  "starts_at": "2018-07-20",
  "status": "accepted",
  "custom_fields": {
    "employment_type": "Contractor",
    "favorite_station": "The Swan",
    "best_seasons": null,
    "start_date": "2004-09-21",
    "willing_to_negotiate": null,
    "salary": "Around $100k",
    "notes": "This is a note field"
  },
  "keyed_custom_fields": {
    "time_type": {
      "name": "Employment Type",
      "type": "single_select",
      "value": "Contractor"
    },
    "favorite_station": {
      "name": "Favorite Station",
      "type": "single_select",
      "value": "The Swan"
    },
    "best_seasons": {
      "name": "Best seasons",
      "type": "multi_select",
      "value": null
    },
    "start_date": {
      "name": "Start Date",
      "type": "date",
      "value": "2004-09-21"
    },
    "will_negotiate": {
      "name": "Willing to negotiate",
      "type": "yes_no",
      "value": null
    },
    "salary": {
      "name": "Salary",
      "type": "short_text",
      "value": "Around $100k"
    },
    "notes": {
      "name": "Notes",
      "type": "long_text",
      "value": "This is a note field"
    }
  }
},
  {
    "id": 1142765,
    "version": 1,
    "application_id": 91078894,
    "job_id": 837749,
    "candidate_id": 7327285,
    "created_at": "2018-06-06T20:21:15.639Z",
    "updated_at": "2018-06-06T20:21:29.796Z",
    "sent_at": null,
    "resolved_at": null,
    "starts_at": "2018-06-30",
    "status": "deprecated",
    "custom_fields": {
      "employment_type": "Part-Time",
      "favorite_station": "The Looking Glass",
      "best_seasons": ["Season 1", "Season 2"],
      "start_date": "2014-05-01",
      "willing_to_negotiate": true,
      "salary": {
        "value": 42000,
        "currency": "EUR"
      },
      "notes": "Very excited to start working with this candidate"
    },
    "keyed_custom_fields": {
      "time_type": {
        "name": "Employment Type",
        "type": "single_select",
        "value": "Part-Time"
      },
      "favorite_station": {
        "name": "Favorite Station",
        "type": "single_select",
        "value": "The Looking Glass"
      },
      "best_seasons": {
        "name": "Best seasons",
        "type": "multi_select",
        "value": ["Season 1", "Season 2"]
      },
      "start_date": {
        "name": "Start Date",
        "type": "date",
        "value": "2014-05-01"
      },
      "will_negotiate": {
        "name": "Willing to negotiate",
        "type": "yes_no",
        "value": true
      },
      "salary": {
        "name": "Salary",
        "type": "currency",
        "value": {
          "value": 42000,
          "currency": "EUR"
        }
      },
      "notes": {
        "name": "Notes",
        "type": "long_text",
        "value": "Very excited to start working with this candidate"
      }
    }
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/offers

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
created_beforeReturn only offers that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_afterReturn only offers that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_beforeReturn only offers that were updated at or before this timestamp. Timestamp must be in in ISO-8601 format.
updated_afterReturn only offers that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.
resolved_afterReturn only offers that were resolved at or after this timestamp. Timestamp must be in in ISO-8601 format.
resolved_beforeReturn only offers that were resolved at or before this timestamp. Timestamp must be in in ISO-8601 format.
statusReturn only offers that have a particular status. One of: unresolved, accepted, rejected, deprecated.
sent_afterReturn only offers that have been sent on or after the provided date. Date must be in YYYY-MM-DD format.
sent_beforeReturn only offers that have been sent on or before the provided date. Date must be in YYYY-MM-DD format.


See noteworthy response attributes.

GET: List Offers for Application

curl 'https://harvest.greenhouse.io/v1/applications/{application_id}/offers'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
[
  {
  "id": 1142785,
  "version": 1,
  "application_id": 91078894,
  "job_id": 837749,
  "candidate_id": 7327285,
  "created_at": "2018-06-06T20:23:10.378Z",
  "updated_at": "2018-06-06T20:23:43.388Z",
  "sent_at": "2018-06-07",
  "resolved_at": "2018-06-06T20:23:43.387Z",
  "starts_at": "2018-07-20",
  "status": "accepted",
  "custom_fields": {
    "employment_type": "Contractor",
    "favorite_station": "The Swan",
    "best_seasons": null,
    "start_date": "2004-09-21",
    "willing_to_negotiate": null,
    "salary": "Around $100k",
    "notes": "This is a note field"
  },
  "keyed_custom_fields": {
    "time_type": {
      "name": "Employment Type",
      "type": "single_select",
      "value": "Contractor"
    },
    "favorite_station": {
      "name": "Favorite Station",
      "type": "single_select",
      "value": "The Swan"
    },
    "best_seasons": {
      "name": "Best seasons",
      "type": "multi_select",
      "value": null
    },
    "start_date": {
      "name": "Start Date",
      "type": "date",
      "value": "2004-09-21"
    },
    "will_negotiate": {
      "name": "Willing to negotiate",
      "type": "yes_no",
      "value": null
    },
    "salary": {
      "name": "Salary",
      "type": "short_text",
      "value": "Around $100k"
    },
    "notes": {
      "name": "Notes",
      "type": "long_text",
      "value": "This is a note field"
    }
  }
},
  {
    "id": 1142765,
    "version": 1,
    "application_id": 91078894,
    "job_id": 837749,
    "candidate_id": 7327285,
    "created_at": "2018-06-06T20:21:15.639Z",
    "updated_at": "2018-06-06T20:21:29.796Z",
    "sent_at": null,
    "resolved_at": null,
    "starts_at": "2018-06-30",
    "status": "deprecated",
    "custom_fields": {
      "employment_type": "Part-Time",
      "favorite_station": "The Looking Glass",
      "best_seasons": ["Season 1", "Season 2"],
      "start_date": "2014-05-01",
      "willing_to_negotiate": true,
      "salary": {
        "value": 42000,
        "currency": "EUR"
      },
      "notes": "Very excited to start working with this candidate"
    },
    "keyed_custom_fields": {
      "time_type": {
        "name": "Employment Type",
        "type": "single_select",
        "value": "Part-Time"
      },
      "favorite_station": {
        "name": "Favorite Station",
        "type": "single_select",
        "value": "The Looking Glass"
      },
      "best_seasons": {
        "name": "Best seasons",
        "type": "multi_select",
        "value": ["Season 1", "Season 2"]
      },
      "start_date": {
        "name": "Start Date",
        "type": "date",
        "value": "2014-05-01"
      },
      "will_negotiate": {
        "name": "Willing to negotiate",
        "type": "yes_no",
        "value": true
      },
      "salary": {
        "name": "Salary",
        "type": "currency",
        "value": {
          "value": 42000,
          "currency": "EUR"
        }
      },
      "notes": {
        "name": "Notes",
        "type": "long_text",
        "value": "Very excited to start working with this candidate"
      }
    }
  }
]

List the offers associated with an application. Greenhouse keeps offer history as updates are made over time.

HTTP Request

GET https://harvest.greenhouse.io/v1/applications/{application_id}/offers

URL Parameters

ParameterDescription
application_idID of the application whose offers you want to retrieve

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.


See noteworthy response attributes.

GET: Retrieve Current Offer for Application

curl 'https://harvest.greenhouse.io/v1/applications/{application_id}/offers/current_offer' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
{
  "id": 1142768,
  "version": 2,
  "application_id": 91078894,
  "job_id": 837749,
  "candidate_id": 7327285,
  "created_at": "2018-06-06T20:21:29.911Z",
  "updated_at": "2018-06-06T20:24:30.707Z",
  "sent_at": "2018-06-06",
  "resolved_at": null,
  "starts_at": "2018-06-30",
  "status": "unresolved",
  "custom_fields": {
    "employment_type": "Contractor",
    "favorite_station": "The Swan",
    "best_seasons": null,
    "start_date": null,
    "willing_to_negotiate": null,
    "salary": "$123,000",
    "notes": "This is a note field"
  },
  "keyed_custom_fields": {
    "time_type": {
      "name": "Employment Type",
      "type": "single_select",
      "value": "Contractor"
    },
    "favorite_station": {
      "name": "Favorite Station",
      "type": "single_select",
      "value": "The Swan"
    },
    "best_seasons": {
      "name": "Best seasons",
      "type": "multi_select",
      "value": null
    },
    "start_date": {
      "name": "Start Date",
      "type": "date",
      "value": null
    },
    "will_negotiate": {
      "name": "Willing to negotiate",
      "type": "yes_no",
      "value": null
    },
    "salary": {
      "name": "Salary",
      "type": "currency",
      "value": "$123,000"
    },
    "notes": {
      "name": "Notes",
      "type": "long_text",
      "value": "This is a note field"
    }
  }
}

Fetch the current offer for an application.

HTTP Request

GET https://harvest.greenhouse.io/v1/applications/{application_id}/offers/current_offer

URL Parameters

ParameterDescription
application_idID of the application whose current offer you want to retrieve


See noteworthy response attributes.

GET: Retrieve Offer

curl 'https://harvest.greenhouse.io/v1/offers/{id}' 
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
{
  "id": 1142785,
  "version": 1,
  "application_id": 91081818,
  "job_id": 84593,
  "candidate_id": 7328851,
  "created_at": "2018-06-06T20:23:10.378Z",
  "updated_at": "2018-06-06T20:23:43.388Z",
  "sent_at": "2018-06-07",
  "resolved_at": "2018-06-06T20:23:43.387Z",
  "starts_at": "2018-07-20",
  "status": "accepted",
  "custom_fields": {
    "employment_type": "Contractor",
    "favorite_station": "The Swan",
    "best_seasons": null,
    "start_date": "2004-09-21",
    "willing_to_negotiate": null,
    "salary": "Around $100k",
    "notes": "This is a note field"
  },
  "keyed_custom_fields": {
    "time_type": {
      "name": "Employment Type",
      "type": "single_select",
      "value": "Contractor"
    },
    "favorite_station": {
      "name": "Favorite Station",
      "type": "single_select",
      "value": "The Swan"
    },
    "best_seasons": {
      "name": "Best seasons",
      "type": "multi_select",
      "value": null
    },
    "start_date": {
      "name": "Start Date",
      "type": "date",
      "value": "2004-09-21"
    },
    "will_negotiate": {
      "name": "Willing to negotiate",
      "type": "yes_no",
      "value": null
    },
    "salary": {
      "name": "Salary",
      "type": "short_text",
      "value": "Around $100k"
    },
    "notes": {
      "name": "Notes",
      "type": "long_text",
      "value": "This is a note field"
    }
  }
}

Retrieve an offer by its ID.

HTTP Request

GET https://harvest.greenhouse.io/v1/offers/{id}

URL Parameters

ParameterDescription
idID of the offer to retrieve


See noteworthy response attributes.

Offices

The office object

An organization’s offices.

With render_as=list (default)

{
  "id": 47012,
  "name": "New York",
  "location": {
      "name": "New York, United States"
  },
  "primary_contact_user_id": 485538,
  "parent_id": 50849,
  "child_ids": [
      50891,
      50852
  ],
  "external_id": "12345"
}

With render_as=tree

{
  "id": 47012,
  "name": "New York",
  "location": {
      "name": "New York, United States"
  },
  "primary_contact_user_id": 485538,
  "external_id": "12345",
  "children": [
      {
          "id": 50891,
          "name": "Utica",
          "location": {
              "name": "Utica, New York, United States"
          },
          "primary_contact_user_id": 336474,
          "external_id": "45647",
          "children": []
      },
      {
          "id": 50852,
          "name": "New York City",
          "location": {
              "name": "New York, New York, United States"
          },
          "primary_contact_user_id": 676259,
          "external_id": "67890",
          "children": []
      }
  ]
}

Noteworthy attributes

AttributeDescription
idThe office’s unique identifier
nameThe office’s name
locationThe office’s location
external_idAn arbitrary ID provided by an external source; does not map to another entity in Greenhouse.

GET: List Offices

curl 'https://harvest.greenhouse.io/v1/offices'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

With render_as=list (default)

[
  {
    "id": 50891,
    "name": "Utica",
    "location": {
        "name": "Utica, New York, United States"
    },
    "primary_contact_user_id": 336474,
    "parent_id": 47012,
    "child_ids": [],
    "external_id": "45647"
  },
  {
    "id": 47012,
    "name": "New York",
    "location": {
        "name": "New York, United States"
    },
    "primary_contact_user_id": 485538,
    "parent_id": 50849,
    "child_ids": [
        50891,
        50852
    ],
    "external_id": "12345"
  },
  {
    "id": 50852,
    "name": "New York City",
    "location": {
        "name": "New York, New York, United States"
    },
    "primary_contact_user_id": 676259,
    "parent_id": 47012,
    "child_ids": [],
    "external_id": "67890"
  }
]

With render_as=tree

[
  {
    "id": 50891,
    "name": "Utica",
    "location": {
        "name": "Utica, New York, United States"
    },
    "primary_contact_user_id": 336474,
    "parent_id": 47012,
    "child_ids": [],
    "external_id": "45647"
  },
  {
    "id": 47012,
    "name": "New York",
    "location": {
        "name": "New York, United States"
    },
    "primary_contact_user_id": 485538,
    "parent_id": 50849,
    "child_ids": [
        50891,
        50852
    ],
    "external_id": "12345"
  },
  {
    "id": 50852,
    "name": "New York City",
    "location": {
        "name": "New York, New York, United States"
    },
    "primary_contact_user_id": 676259,
    "parent_id": 47012,
    "child_ids": [],
    "external_id": "67890"
  }
]

List all of an organization’s offices.

HTTP Request

GET https://harvest.greenhouse.io/v1/offices

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
render_asThis parameter defines how to represent the list of offices. The default value is ‘list’, which returns a flat list of offices. If this is set to 'tree’, offices are represented in a tree-like structure where they may include sub-offices as children


See noteworthy response attributes.

GET: Retrieve Office

curl 'https://harvest.greenhouse.io/v1/offices/{id}'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

{
  "id": 47012,
  "name": "New York",
  "location": {
      "name": "New York, United States"
  },
  "primary_contact_user_id": 485538,
  "parent_id": 50849,
  "child_ids": [
      50891,
      50852
  ],
  "external_id": "12345"
}

With render_as=tree

{
  "id": 47012,
  "name": "New York",
  "location": {
      "name": "New York, United States"
  },
  "primary_contact_user_id": 485538,
  "external_id": "12345",
  "children": [
      {
          "id": 50891,
          "name": "Utica",
          "location": {
              "name": "Utica, New York, United States"
          },
          "primary_contact_user_id": 336474,
          "external_id": "45647",
          "children": []
      },
      {
          "id": 50852,
          "name": "New York City",
          "location": {
              "name": "New York, New York, United States"
          },
          "primary_contact_user_id": 676259,
          "external_id": "67890",
          "children": []
      }
  ]
}

Retrieve an office by its ID.

HTTP Request

GET https://harvest.greenhouse.io/v1/offices/{id}

URL Parameters

ParameterDescription
idThe ID of the office to retrieve

Querystring parameters

ParameterDescription
render_asThis parameter defines how to represent the list of offices. The default value is 'list’, which returns a flat list of offices. If this is set to 'tree’, offices are represented in a tree-like structure where they may include sub-offices as children


See noteworthy response attributes.

PATCH: Edit Office

curl -X PATCH 'https://harvest.greenhouse.io/v1/offices/{id}'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
   "name": "Research and Development",
   "location": "New York, NY",
   "external_id": "1234567890"
}

The above command returns a JSON response, structured like this:

{
  "id": 50891,
  "name": "Utica",
  "location": {
      "name": "Utica, New York, United States"
  },
  "primary_contact_user_id": 336474,
  "parent_id": 47012,
  "child_ids": [],
  "external_id": "45647"
}

Edit an office’s basic information.

HTTP Request

PATCH https://harvest.greenhouse.io/v1/offices/{id}

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

ParameterRequiredTypeDescription
nameYesstringThe office’s name. If included, this cannot be blank.
locationNostringThe office’s location.
external_id*NostringThe office’s external ID. If included, this must be unique to this office within the organization.

* - If the external id feature is not enabled for your organization, attempting to edit this field will raise an API Error.

POST: Add Office

curl -X POST 'https://harvest.greenhouse.io/v1/offices'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command takes a JSON request, structured like this:

{
  "name": "Brooklyn",
  "parent_id": 47012,
  "primary_contact_user_id": 336474,
  "location": "Brooklyn, NY"
}

The above command returns a JSON response, structured like this:

{
  "id": 58028,
  "name": "Brooklyn",
  "location": {
      "name": "Brooklyn, NY"
  },
  "primary_contact_user_id": 336474,
  "parent_id": 47012,
  "child_ids": [],
  "external_id": null
}

Create a new office

HTTP Request

POST https://harvest.greenhouse.io/v1/offices

Headers

HeaderDescription
On-Behalf-OfID of the user issuing this request. Required for auditing purposes. Must be a user who can create offices.

JSON Body Parameters

ParameterRequiredTypeDescription
nameyesstringThe name of your new office. Must be less than 255 characters and unique within your organization.
locationnostringThis is a text representation of the office’s location. This is free-form text. It is not geo-located.
primary_contact_user_idnonumberThe id of the user who will be the primary in-house contact for this office. This user must be a site-admin.
parent_id*nonumberThe office id for the new office to be nested under. If this isn’t included, the office will be created at the top level.
external_id**nostringThe external_id for the office.

* - The tiered office feature is available only for customers with the Pro or Enterprise Greenhouse Recruiting package. Use of this field will return an error for other Greenhouse Recruiting customers.

** - The external_id feature is available only for customers with the Enterprise Greenhouse Recruiting package. Use of this field will return an error for other Greenhouse Recruiting customers.

Prospect Pools

The prospect pools object

An organization’s prospect pools.

{
    "id": 25,
    "name": "Cold Outreach: Sourced",
    "active": true,
    "prospect_stages": [
        {
            "id": 85,
            "name": "Discussed"
        },
        {
            "id": 86,
            "name": "Had email listed on their blog"
        }
    ]
}

Noteworthy attributes

AttributeDescription
idThe pool’s unique identifier
activetrue or false. False means the pool is hidden from view in Greenhouse.

GET: List Prospect Pools

curl 'https://harvest.greenhouse.io/v1/prospect_pools'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns a JSON response, structured like this:

[
    {
        "id": 25,
        "name": "Cold Outreach: Sourced",
        "active": true,
        "prospect_stages": [
            {
                "id": 85,
                "name": "Discussed"
            },
            {
                "id": 86,
                "name": "Had email listed on their business card"
            },
            {
                "id": 87,
                "name": "Had email listed on their blog"
            },
            {
                "id": 88,
                "name": "Not Contacted"
            }
        ]
    },
    {
        "id": 26,
        "name": "Opted In: Referral",
        "active": false,
        "prospect_stages": [
            {
                "id": 90,
                "name": "1st. Follow Up Sent"
            },
            {
                "id": 91,
                "name": "2nd Follow Up Sent"
            },
            {
                "id": 92,
                "name": "In Discussion"
            },
            {
                "id": 93,
                "name": "Discussed"
            },
            {
                "id": 94,
                "name": "Had email listed on their github profile"
            }
        ]
    }
]

List all of an organization’s prospect pools.

HTTP Request

GET https://harvest.greenhouse.io/v1/prospect_pools

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.


See noteworthy response attributes.

GET: Retrieve Prospect Pool

curl 'https://harvest.greenhouse.io/v1/prospect_pools/{id}'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns a JSON response, structured like this:

{
    "id": 25,
    "name": "Cold Outreach: Sourced",
    "active": true,
    "prospect_stages": [
        {
            "id": 85,
            "name": "Discussed"
        },
        {
            "id": 86,
            "name": "Had email listed on their blog"
        }
    ]
}

HTTP Request

GET https://harvest.greenhouse.io/v1/prospect_pools/{id}

URL Parameters

ParameterDescription
idThe ID of the prospect pool to retrieve


See noteworthy response attributes.

Rejection Reasons

The rejection reason object

Represents rejection reasons configured by an organization under the Custom Options section of Greenhouse.

{
  "id": 262,
  "name": "Missing resume",
  "type": {
    "id": 1,
    "name": "We rejected them"
  }
}

Noteworthy attributes

AttributeDescription
idThe rejection reason’s unique identifier
nameThe rejection reason’s name
typeOne of {"id": 1, "name": "We rejected them"}, {"id": 2, "name": "They rejected us"}, {"id": 3, "name": "None specified"}

GET: List Rejection Reasons

curl 'https://harvest.greenhouse.io/v1/rejection_reasons'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 262,
    "name": "Missing resume",
    "type": {
      "id": 1,
      "name": "We rejected them"
    }
  },
  {
    "id": 280,
    "name": "Not in NYC",
    "type": {
      "id": 1,
      "name": "We rejected them"
    }
  },
  {
    "id": 230,
    "name": "Hiring Freeze",
    "type": {
      "id": 2,
      "name": "None specified"
    }
  }
]

List all of an organization’s rejection reasons.

HTTP Request

GET https://harvest.greenhouse.io/v1/rejection_reasons

Querystring parameters

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
include_defaultsWhen included and set to true, this will also return Greenhouse’s default rejection reasons which are included automatically in each account.


See noteworthy response attributes.

Scheduled Interviews

The scheduled interview object

Interviews that have been scheduled for the specified application. Note that all-day interviews will have a start and end date with no specified time.

{
  "id": 9128481,
  "application_id": 4684156,
  "start": {
    "date_time": "2014-03-26T22:15:00.000Z"
  },
  "end": {
    "date_time": "2014-03-26T22:30:00.000Z"
  },
  "location": "Big Conference Room",
  "status": "awaiting_feedback",
  "created_at": "2016-02-10T14:31:51.019Z",
  "updated_at": "2016-05-23T20:43:11.679Z",
  "interview": {
    "id": 7001,
    "name": "Culture Fit"
  },
  "organizer": {
    "id": 2000,
    "first_name": "Jack",
    "last_name": "Shepard",
    "name": "Jack Shepard",
    "employee_id": "12345"
  },
  "interviewers": [
    {
      "id": 4080,
      "name": "Kate Austen",
      "email": "kate.austen@example.com",
      "scorecard_id": 11274
    }
  ]
}

Noteworthy attributes

AttributeDescription
idThe scheduled interview’s unique identifier
startA date_time value if this interview has a precise start time, or a date value if this is an all-day event.
endA date_time value if this interview has a precise start time, or a date value if this is an all-day event.
locationThe location of the interview.
statusOne of: scheduled, awaiting_feedback, complete
organizerThe user who is the organizer for this interview
interviewersAn array containing the users who have interviews with this candidate, including, if applicable, the ID of the scorecard they completed.

GET: List Interviews

curl 'https://harvest.greenhouse.io/v1/scheduled_interviews'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

[
  {
    "id": 9128481,
    "application_id": 4684156,
    "start": {
      "date_time": "2014-03-26T22:15:00.000Z"
    },
    "end": {
      "date_time": "2014-03-26T22:30:00.000Z"
    },
    "location": "Big Conference Room",
    "status": "awaiting_feedback",
    "created_at": "2016-02-10T14:31:51.019Z",
    "updated_at": "2016-05-23T20:43:11.679Z",
    "interview": {
      "id": 7001,
      "name": "Culture Fit"
    },
    "organizer": {
      "id": 2000,
      "first_name": "Jack",
      "last_name": "Shepard",
      "name": "Jack Shepard",
      "employee_id": "12345"
    },
    "interviewers": [
      {
        "id": 4080,
        "name": "Kate Austen",
        "email": "kate.austen@example.com",
        "scorecard_id": 11274
      }
    ]
  },
  {
    "id": 9128482,
    "application_id": 432905,
    "start": {
      "date": "2017-08-22"
    },
    "end": {
      "date": "2017-08-23"
    },
    "location": "Small Conference Room",
    "status": "complete",
    "interview": {
      "id": 7002,
      "name": "Whiteboarding Challenge"
    },
    "organizer": {
      "id": 2000,
      "first_name": "Jack",
      "last_name": "Shepard",
      "name": "Jack Shepard",
      "employee_id": "12345"
    },
    "interviewers": [
      {
        "id": 3412,
        "name": "Charlie Pace",
        "email": "youalleverybody@example.com",
        "scorecard_id": null
      }
    ]
  }
]

List all of an organization’s scheduled interviews.

HTTP Request

GET https://harvest.greenhouse.io/v1/scheduled_interviews

Optional querystring Parameters

Timestamps must be in in ISO-8601 format.

ParameterDescription
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
created_beforeOnly return scheduled interviews that were created before this timestamp.
created_afterOnly return scheduled interviews that were created at or after this timestamp.
updated_beforeOnly return scheduled interviews that were updated before this timestamp.
updated_afterOnly return scheduled interviews that were updated at or after this timestamp.
starts_beforeOnly return scheduled interviews scheduled to start before this timestamp.
starts_afterOnly return scheduled interviews scheduled to start at or after this timestamp.
ends_beforeOnly return scheduled interviews scheduled to end before this timestamp.
ends_afterOnly return scheduled interviews scheduled to end at or after this timestamp.

GET: List Interviews for Application

curl 'https://harvest.greenhouse.io/v1/applications/{id}/scheduled_interviews'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
[
  {
    "id": 9128481,
    "application_id": 4684156,
    "start": {
      "date_time": "2014-03-26T22:15:00.000Z"
    },
    "end": {
      "date_time": "2014-03-26T22:30:00.000Z"
    },
    "location": "Big Conference Room",
    "status": "awaiting_feedback",
    "created_at": "2016-02-10T14:31:51.019Z",
    "updated_at": "2016-05-23T20:43:11.679Z",
    "interview": {
      "id": 7001,
      "name": "Culture Fit"
    },
    "organizer": {
      "id": 2000,
      "first_name": "Jack",
      "last_name": "Shepard",
      "name": "Jack Shepard",
      "employee_id": "12345"
    },
    "interviewers": [
      {
        "id": 4080,
        "name": "Kate Austen",
        "email": "kate.austen@example.com",
        "scorecard_id": 11274
      }
    ]
  },
  {
    "id": 9128482,
    "application_id": 4684156,
    "start": {
      "date": "2017-08-22"
    },
    "end": {
      "date": "2017-08-23"
    },
    "location": "Small Conference Room",
    "status": "complete",
    "interview": {
      "id": 7002,
      "name": "Whiteboarding Challenge"
    },
    "organizer": {
      "id": 2000,
      "first_name": "Jack",
      "last_name": "Shepard",
      "name": "Jack Shepard",
      "employee_id": "12345"
    },
    "interviewers": [
      {
        "id": 3412,
        "name": "Charlie Pace",
        "email": "youalleverybody@example.com",
        "scorecard_id": null
      }
    ]
  }
]

Interviews that have been scheduled for this application.

HTTP Request

GET https://harvest.greenhouse.io/v1/applications/{id}/scheduled_interviews

Querystring Parameters

ParameterDescription
idID of the application to retrieve
per_pageReturn up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
pageA cursor for use in pagination. Returns the n-th chunk of per_page objects.
created_beforeReturn only scheduled interviews that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_afterReturn only scheduled interviews that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_beforeReturn only scheduled interviews that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_afterReturn only scheduled interviews that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.


See noteworthy response attributes.

GET: Retrieve Interview

curl 'https://harvest.greenhouse.io/v1/scheduled_interviews/{id}'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
{
  "id": 9128481,
  "application_id": 4684156,
  "start": {
    "date_time": "2014-03-26T22:15:00.000Z"
  },
  "end": {
    "date_time": "2014-03-26T22:30:00.000Z"
  },
  "location": "Big Conference Room",
  "status": "awaiting_feedback",
  "created_at": "2016-02-10T14:31:51.019Z",
  "updated_at": "2016-05-23T20:43:11.679Z",
  "interview": {
    "id": 7001,
    "name": "Culture Fit"
  },
  "organizer": {
    "id": 2000,
    "first_name": "Jack",
    "last_name": "Shepard",
    "name": "Jack Shepard",
    "employee_id": "12345"
  },
  "interviewers": [
    {
      "id": 4080,
      "name": "Kate Austen",
      "email": "kate.austen@example.com",
      "scorecard_id": 11274
    }
  ]
}

Retrieve an interview by its ID.

HTTP Request

GET https://harvest.greenhouse.io/v1/scheduled_interviews/{id}

URL Parameters

ParameterDescription
idThe ID of the scheduled interview to retrieve

Scorecards

All submitted scorecards ordered by candidate.

The scorecard object

{
  "id": 123,
  "updated_at": "2016-08-22T19:52:38.384Z",
  "created_at": "2016-08-22T19:52:38.384Z",
  "interview": "Application Review",
  "candidate_id": 1234,
  "application_id": 3456,
  "interviewed_at": "2016-08-18T16:00:00.000Z",
  "submitted_by": {
    "id": 4080,
    "first_name": "Kate",
    "last_name": "Austen",
    "name": "Kate Austen",
    "employee_id": "12345"
  },
  "submitted_at": "2014-03-26T21:59:51Z",
  "overall_recommendation": "yes",
  "attributes": [
    {
      "name": "Communication",
      "type": "Skills",
      "note": "What a great communicator!",
      "rating": "yes"
    },
    {
      "name": "Adaptable",
      "type": "Skills",
      "note": null,
      "rating": "yes"
    },
    {
      "name": "Relationship Manager",
      "type": "Skills",
      "note": null,
      "rating": "mixed"
    },
    {
      "name": "Project Management",
      "type": "Qualifications",
      "note": null,
      "rating": "mixed"
    },
    {
      "name": "Problem Solver",
      "type": "Qualifications",
      "note": null,
      "rating": "no"
    },
    {
      "name": "Analytical",
      "type": "Skills",
      "note": null,
      "rating": "definitely_not"
    }
  ],
  "ratings": {
    "definitely_not": [
      "Analytical"
    ],
    "no": [
      "Problem Solver"
    ],
    "mixed": [
      "Relationship Manager",
      "Project Management"
    ],
    "yes": [
      "Communication",
      "Adaptable"
    ],
    "strong_yes": []
  },
  "questions": [
    {
      "id": null,
      "question": "Key Take-Aways",
      "answer": "Seems like a decent candidate."
    },
    {
      "id": null,
      "question": "Private Notes",
      "answer": "Seems like a decent candidate."
    },
    {
      "id": 1234567,
      "question": "Does the candidate have experience designing APIs?",
      "answer": "Yes"
    },
    {
      "id": 1234568,
      "question": "Which team would you suggest for this candidate?",
      "answer": "Alpha Team"
    },
    {
      "id": 1234569,
      "question": "Where would the candidate be willing to work?",
      "answer": "London, Dubai, San Diego"
    }
  ]
}

Noteworthy attributes

AttributeDescription
idThe scorecard’s unique identifier
candidate_idThe ID of the candidate whom this scorecard was written for.
submitted_byThe user who submitted this scorecard.
overall_recommendationOne of: definitely_not, no, yes, strong_yes, no_decision
attributesArray containing the attributes of the Scorecard. Describes each attribute’s name, type, rating (can be “no_decision”), and an optional note.

GET: List Scorecards

curl 'https://harvest.greenhouse.io/v1/scorecards'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

The above command returns JSON structured like this:

[
  {
    "id": 123,
    "updated_at": "2016-08-22T19:52:38.384Z",
    "created_at": "2016-08-22T19:52:38.384Z",
    "interview": "Application Review",
    "candidate_id": 1234,
    "application_id": 3456,
    "interviewed_at": "2016-08-18T16:00:00.000Z",
    "submitted_by": {
      "id": 4080,
      "first_name": "Kate",
      "last_name": "Austen",
      "name": "Kate Austen",
      "employee_id": "12345"
    },
    "submitted_at": "2014-03-26T21:59:51Z",
    "overall_recommendation": "yes",
    "attributes": [
      {
        "name": "Communication",
        "type": "Skills",
        "note": "What a great communicator!",
        "rating": "yes"
      },
      {
        "name": "Adaptable",
        "type": "Skills",
        "note": null,
        "rating": "yes"
      },
      {
        "name": "Relationship Manager",
        "type": "Skills",
        "note": null,
        "rating": "mixed"
      },
      {
        "name": "Project Management",
        "type": "Qualifications",
        "note": null,
        "rating": "mixed"
      },
      {
        "name": "Problem Solver",
        "type": "Qualifications",
        "note": null,
        "rating": "no"
      },
      {
        "name": "Analytical",
        "type": "Skills",
        "note": null,
        "rating": "definitely_not"
      }
    ],
    "ratings": {
      "definitely_not": [
        "Analytical"
      ],
      "no": [
        "Problem Solver"
      ],
      "mixed": [
        "Relationship Manager",
        "Project Management"
      ],
      "yes": [
        "Communication",
        "Adaptable"
      ],
      "strong_yes": []
    },
    "questions": [
      {
        "id": null,
        "question": "Key Take-Aways",
        "answer": "Seems like a decent candidate."
      },
      {
        "id":