NAV
Developers Home
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.

Rate limiting

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

Harvest API requests for approved Greenhouse partners and customer-built custom integrations are limited to the amount specified in the returned X-RateLimit-Limit header, per 10 seconds. Unlisted vendors may be subject to additional rate limits.

Exceeding the limit will return an HTTP 429 response. Status requests for approved integrations can be checked using the X-RateLimit-Remaining header. In the HTTP 429 response, the X-RateLimit-Reset header is the timestamp indicating when you can try again while the Retry-After header is the number of seconds indicating when you can try again.

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 Code Meaning
401 Unauthorized – Ensure you’re using a valid Harvest API key with the correct permissions in the Authorization header (Basic Auth).
403 Forbidden -- You don't have access to that record.
404 Not Found -- Resource not found.
422 Not processed – We're not able to process your request. Validate your parameters.
429 Rate limit exceeded – You're being throttled for exceeding our rate limit.
500 Server error – We're having a problem with our server. Give us a few minutes and try again, or check our status page

Harvest Change Log

The timestamps below are Eastern Time.

Date Description
Aug 7, 2024 7:00:00AM Replaced 'web hook' with webhook
Jul 10, 2024 7:00:00AM Updated The job object openings[].opened_at and The job opening object opened_at param descriptions
Jul 9, 2024 9:00:00AM Updated POST: Reject Application rejection_email.send_email_at param documentation to indicate the time zone
Jun 8, 2024 3:10:00PM Add ability to update custom fields in rejection details to PATCH: Update Application
Jun 13, 2024 5:00:00PM Updated Introduction - Pagination last param, and all list endpoint documentation using old pagination to include skip_count param
Jun 13, 2024 5:00:00PM Updated Introduction - Pagination last param, and all list endpoint documentation using old pagination to include skip_count param
Apr 12, 2024 9:30:00AM Updated sample response in the GET: List Offices and GET: Retrieve Office documentation
Mar 25, 2024 9:15:00AM Updated job_id description in the GET: List Candidates section
Mar 21, 2024 3:15:00PM Updated description in the Rate-Limiting section
Feb 23 2024 1:00:00PM Updated description of the application parameter in the POST: Add Prospect documentation
Dec 11, 2023 4:00:00PM Added a Note to PATCH: Update Current Offer documentation
Nov 15, 2023 12:45:00PM Added job_post_custom_location_id field to Job Post response object and updated sample response
Nov 13, 2023 11:09:00AM Update error status code message.
Oct 30, 2023 3:20:00PM Removed language indicating PUT: Anonymize Candidate is restricted to Expert Tier
Oct 12, 2023 2:15:00PM Updated Throttling section to Rate limiting and updated description
Aug 22, 2023 3:00:00PM Included active attribute in the Job Stage Object
Aug 22, 2023 3:00:00PM Fixed URL expiry timing in General Considerations and the Candidate Object
May 15, 2023 12:00:00PM Added ability to update closed openings in the Edit Openings Endpoint
April 12, 2023 3:00:00PM Modified format of request links for POST: Scheduled Interviews and PATCH: Scheduled Interviews.
March 7, 2023 10:00:00AM Modified intenal querystring parameter on job post GET requests to work in the reverse manner. When included in a request and set to false, the response will only include external job posts.
February 28, 2023 12:00:00PM Added internal querystring paramater to job post GET requests to return only internal job posts. When included in a request and set to true, the response will only include internal job posts.
November 21, 2022 12:00:00PM Deprecated version 1 of the DELETE: Destroy Openings endpoint. Only v2 is available going forward.
November 9, 2022 04:00:00PM The full_content querystring parameter has been modified on job post GET requests to return Pay Transparency ranges (if present). When included in a request, the "content" or "internal_content" fields will return a concatenated string that includes the Board-level introduction, the Post-level description, pay transparency ranges, and the Board-level conclusion.
October 18, 2022 12:00:00PM Added ability to create and update User Attributes to the Users endpoints
September 22, 2022 12:00:00PM Updated DELETE: Destroy Openings to a v2 endpoint. The v1 endpoint will be deprecated in a future release. Users and partners should switch over to the v2 endpoint as soon as possible to avoid issues with your integration.
September 12, 2022 12:00:00PM Added created_at field for application's attachments object.
September 9, 2022 12:00:00PM Added PATCH: Convert Prospect To Candidate endpoint to allow conversion of a prospect application to a candidate application on a selected job.
August 1, 2022 12:00:00PM Making content_type required for attachments unless uploading using a URL.
May 18, 2021 12:00:00PM Added video_conferencing_url to Scheduled Interview object.
May 3, 2021 05:00:00PM Added priority to Job Stages object.
May 3, 2021 04:00:00PM Added job_post_id field to application's response object.
April 21, 2021 11:00:00AM Added ability to change external_id for custom field options.
April 13, 2021 01:00:00PM Added ability to change user permission level to basic.
September 28, 2020 12:00:00PM "Required" field added to Demographic Questions.
September 23, 2020 03:00:00PM Attachments have been added at the application level. Previously, an aggregation of all attachments on all applications was included at the candidate level and not at all in the applications endpoint. Now, the applications endpoint includes attachments specific to each application and the candidates endpoint includes attachments in each application specific to that application.
September 10, 2020 05:00:00PM A new querystring parameter has been added to job post GET requests to return Board-level Introductions and Conclusions (if present). When included in a request, the "content" or "internal_content" fields will return a concatenated string that includes the Board-level introduction, the Post-level description, and the Board-level conclusion.
May 28, 2020 05:00:00PM Candidate photos have been removed from Greenhouse and will no longer be accepted as a field to be anonymized in PUT Anonymize Candidates
May 5, 2020 12:00:00PM Added "interview_step" field to the scorecards response. This provides the "ID" of the existing "interview" field. The "name" sub-element of the "interview_step" element should match the current "interview" element. The "interview" field is maintained for backward compatibility.
Apr 22, 2020 09:00:00AM Added external_id as field to the Custom Field Option object.
Apr 13, 2020 09:00:00AM The V1 endpoints for [PATCH: Edit User], [PATCH: Disable User], and [PATCH: Enable User] have been deprecated. Users should move to the V2 endpoints as soon as convenient. This change was made to take advantage of additional ways to look up users in Greenhouse.
Apr 12, 2020 09:00:00AM V1 of [PATCH: Update Job Post] has been deprecated. Updating a job post's status has been extracted to [PATCH: Update Job Post Status], while updating all other properties remains on [PATCH: Update Job Post]. The new endpoint more accurately reflects the permissions required by the On-Behalf-Of user to access and edit the Job Post's properties.
Apr 5, 2020 09:00:00AM Added V2 of POST: Scheduled Interviews and PATCH: Scheduled Interviews. Deprecated V1.
Jan 30, 2020 05:30:00PM Added ability to update custom field values in a PATCH: Job Openings request
Jan 30, 2020 05:30:00PM Added ability to re-open a closed job opening in a PATCH: Job Openings request
Jan 15, 2020 04:00:00PM Added ability to update a rejection reason on a rejected application. PATCH: Update Rejection Reason
Dec 20, 2019 04:00:00PM Added ability to assign custom field values in a POST: Job Openings request
Nov 26, 2019 11:00:00 AM Updated the error response text to be more descriptive when attempting to delete a required custom field
Nov 26, 2019 11:00:00 AM Added ability to update custom fields on an application's current offer via PATCH: Update Current Offer
Nov 12, 2019 10:00:00 AM Added a v2 version of PATCH: Edit User, PATCH: Disable User, and PATCH: Enable User
Oct 7, 2019 03:00:00 PM Added custom fields to openings on organizations with this option enabled. GET: Openings
Oct 1, 2019 11:00:00AM Added ability to filter offers by start_date with starts_before and starts_after. GET: Offers
Sep 18, 2019 01:00:00PM Added ability to create prospect applications for existing candidates/prospects POST: Add Application to Candidate/Prospect
Aug 12, 2019 05:00:00PM Prospect post data will return in Job Posts endpoints.
Jul 31, 2019 01:00:00PM Added ability to filter demographic data answers by created_at and updated_at dates GET: Demographic Answers
Jul 17, 2019 01:00:00PM Added ability to update the current offer on an application via PATCH: Update Current Offer
Jul 17, 2019 01:00:00PM Added ability to post new attachments to applications via POST: Add Attachment to Application
Jun 26, 2019 12:00:00PM Added ability to create new Offices linked by external parent ids to POST: Add Office.
Jun 26, 2019 12:00:00PM Added ability to create new Departments linked by external parent ids to POST: Add Department.
Jun 26, 2019 12:00:00PM Added child and parent office external IDs to the Office object.
Jun 26, 2019 12:00:00PM Added child and parent department external IDs to the Department object.
Jun 12, 2019 02:00:00PM Added prospective_department and prospective_office to the Application object.
Jun 7, 2019 02:00:00PM Added default interviewers and estimated duration to the Job Stage object
May 24, 2019 01:00:00PM Added ability to set location on job posts via office and custom location id via PATCH: Update Job Post
May 24, 2019 01:00:00PM Added schedulable field to Job Stages Endpoints
May 24, 2019 01:00:00PM Added first_published_at field to Job Posts Endpoints
May 15, 2019 05:00:00PM Added ability to change prospect pool and stage via PATCH: Update Application
May 15, 2019 03:15:00PM Added opening field to Offers.
May 7, 2019 03:30:00PM Added Demographic Data endpoints
Apr 8 , 2019 04:00:00PM Added interviewer to Scorecard object
Mar 18, 2019 03:30:00PM Added ability to delete a Candidate Tag via DELETE: Destroy a Candidate Tag
Mar 6, 2019 02:15:00PM Added linked_candidate_ids to Users Endpoints
Feb 28, 2019 02:34:00PM Added primary_email_address to Users Endpoints
Feb 28, 2019 12:30:00PM Added updated_at to Jobs Endpoints
Feb 13, 2019 03:30:00PM Added ability to create new candidate tags via POST: Add New Candidate Tag
Feb 1, 2019 11:28:00AM Added partial response (HTTP Status code 202) to POST: Create Job
Jan 8, 2019 12:00:00PM Added can_email flag to Candidates Endpoints

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": 123456,
      "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

Attribute Description
id The internal Greenhouse ID of the activity feed note.
note An array of notes associated with this candidate.
email An array of emails sent to and from this candidate.
activity An 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

Parameter Description
id The 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"
        }
    ],
    "job_post_id": 123,
    "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."
        }
    ],
    "prospective_office": null,
    "prospective_department": null,
    "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"
        }
    },
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/...",
            "type": "offer_packet",
            "created_at": "2020-09-27T18:45:27.137Z"
        }
    ]

}

Noteworthy attributes

Attribute Description
id Application ID
prospect If true, this is a prospect application which means that the associated person is a prospect and has not yet applied for this job.
status One of: active, rejected, hired, converted.
jobs An array containing the job that the candidate applied for.
job_post_id The ID of the job post through which the candidate applied. This value is null if the application was created through other means, e.g. manually adding candidates or importing candidates through sourcing integrations
candidate_id The ID of the candidate who is applying for this job.
current_stage The current stage that this application is in.
credited_to.id The ID of the user who will receive credit for this application.
location The contents of the location question on a job post.
answers The 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_fields Contains 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_fields This 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.
prospective_department The department that this prospect application is being considered for.
prospective_office The office that this prospect application is being considered for.

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"
        }
    ],
    "job_post_id": 123,
    "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"
        }
    ],
    "prospective_office": null,
    "prospective_department": null,
    "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"
        }
    },
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/...",
            "type": "offer_packet",
            "created_at": "2020-09-27T18:45:27.137Z"
        }
    ]
},
{
    "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 "
        }
    ],
    "job_post_id": null,
    "status": "hired",
    "current_stage": null,
    "answers": [
      {
          "question": "How did you hear about this job?",
          "answer": "Online Research"
      },
      {
          "question": "Website",
          "answer": "mytestwebsite.com"
      }
    ],
    "prospective_office": {
      "primary_contact_user_id": null,
      "parent_id": null,
      "name": "New York",
      "location": {
        "name": "New York, NY"
      },
      "id": 59213,
      "external_id": null,
      "child_ids": []
    },
    "prospective_department": {
      "parent_id": null,
      "name": "Marketing",
      "id": 9024,
      "external_id": null,
      "child_ids": []
    },
    "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"
        }
    },
    "attachments": [
        {
            "filename": "Jack_Smith_Offer_Packet_09_27_2020.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/...",
            "type": "offer_packet",
            "created_at": "2020-09-27T18:45:27.137Z"
        }
    ]
  }
]

List all of an organization's applications.

HTTP Request

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

Querystring parameters

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
*page A cursor for use in pagination. Returns the n-th chunk of per_page objects.
*skip_count If true, the performance of retrieving applications will improve. This will remove last from the link response header.
created_before Return only applications that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_after Return only applications that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
last_activity_after Return only applications where 'last_activity_at' is at or after this timestamp. Timestamp must be in in ISO-8601 format.
job_id If supplied, only return applications that involve this job. Will return both candidates and prospects.
status If 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"
        }
    ],
    "job_post_id": 123,
    "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"
        }
    ],
    "prospective_office": null,
    "prospective_department": null,
    "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"
        }
    },
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/...",
            "type": "offer_packet",
            "created_at": "2020-09-27T18:45:27.137Z"
        }
    ]
}

Retrieve an application by its id.

HTTP Request

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

URL parameters

Parameter Description
id ID 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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.


See noteworthy response attributes.

POST: Add Application to Candidate/Prospect

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"

To create a prospect application for jobs 123 and 456:

{
  "prospect": "true",
  "job_ids": [123, 456],
  "prospective_office_id": 58319,
  "prospective_department_id": 9021,
  "prospect_pool_id": 1640,
  "prospect_pool_stage_id": 7594,
  "prospect_owner_id": 107468
}

To create a prospect application on no jobs:

{
  "prospect": "true"
}

To create a candidate application:

{
  "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"
    }
  ],
  "job_post_id": null,
  "status": "active",
  "current_stage": {
    "id": 1945557,
    "name": "Application Review"
  },
  "answers": [],
  "custom_fields": {
    "birthday": "1992-01-27",
    "bio": "This is my bio"
  },
  "prospective_office": null,
  "prospective_department": null,
  "prospect_detail": {
    "prospect_pool": null,
    "prospect_stage": null,
    "prospect_owner": null
  }
}

Create a new application for an existing candidate or prospect.

The new application can be a candidate application or a prospect application, depending on the "prospect" parameter which defaults to "false". The JSON body parameters differ depending on whether you are creating a prospect application or a candidate application. The main difference is that prospect applications can be considered for zero, one, or multiple jobs.

HTTP Request

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters for Candidate application

Parameter Required Type Description
job_id Yes integer The ID of the job you want to create an application to for this candidate
source_id No integer The id of the source to be credited for this application
initial_stage_id No integer The ID of the job stage this application will be created in.
referrer No object An object representing the referrer
referrer[type] No string A string representing the type of referrer: 'id', 'email', or 'outside'
referrer[value] No string The id of the user who made the referral (not the referrer id)
attachments No array An array of attachments to be uploaded to this application. See Add Attachment for parameters.

JSON Body Parameters for Prospect application

Parameter Required Type Description
prospect Yes boolean Set to "true" in order to create a prospect application.
job_ids No array An optional array of Job IDs to consider this prospect for.
source_id No integer The id of the source to be credited for this application
referrer No object An object representing the referrer
referrer[type] No string A string representing the type of referrer: 'id', 'email', or 'outside'
referrer[value] No string The id of the user who made the referral (not the referrer id)
prospect_pool_id No integer Prospect Pool ID.
prospect_pool_stage_id No integer Prospect Pool Stage ID. prospect_pool_id is required, and the prospect pool stage must belong to the given prospect pool.
prospect_owner_id No integer User ID of the prospect owner.
prospective_department_id No integer Department ID to consider this prospect for.
prospective_office_id No integer Office ID to consider this prospect for. prospective_department_id is required in order to set a prospective office.

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"
      }
  ],
  "job_post_id": 123,
  "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"
      }
  ],
  "prospective_office": null,
  "prospective_department": null,
  "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"
      }
  },
  "attachments": [
      {
          "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
          "url": "https://prod-heroku.s3.amazonaws.com/...",
          "type": "offer_packet",
          "created_at": "2020-09-27T18:45:27.137Z"
      }
  ]
}

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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
source_id No integer The ID of the application's source
referrer No object An object representing the referrer
referrer[type] No string A string representing the type of referrer: 'id', 'email', or 'outside'
referrer[value] No string The id of the user who made the referral (not the referrer id)
custom_fields[] No custom_field Array of hashes containing new application custom field values. Passing an empty array does nothing. Click here for more information on structuring custom field data for edit requests.
prospect_pool_id No integer The ID of the prospect pool for the application
prospect_stage_id No integer The ID of the prospect pool stage for the application
rejection_details No object An object representing the rejection details of a rejected application. Note: Rejection details can't be updated if the application has not been rejected.
rejection_details[custom_fields[]] No custom_field Array of hashes containing new rejection detail custom field values. Passing an empty array does nothing. Click here for more information on structuring custom field data for edit requests.

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"
      }
  ],
  "job_post_id": null,
  "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"
      }
  ],
  "prospective_office": null,
  "prospective_department": null,
  "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"
      }
  },
  "attachments": [
      {
          "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
          "url": "https://prod-heroku.s3.amazonaws.com/...",
          "type": "offer_packet",
          "created_at": "2020-09-27T18:45:27.137Z"
      }
  ]
}

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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
from_stage_id Yes integer The 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"
      }
  ],
  "job_post_id": null,
  "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"
      }
  ],
  "prospective_office": null,
  "prospective_department": null,
  "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"
      }
  },
  "attachments": [
      {
          "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
          "url": "https://prod-heroku.s3.amazonaws.com/...",
          "type": "offer_packet",
          "created_at": "2020-09-27T18:45:27.137Z"
      }
  ]
}

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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
new_job_id Yes integer The ID of the job to which this application should be transferred
new_stage_id No integer The 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"
    }
  ],
  "job_post_id": 123,
  "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"
    }
  ],
  "prospective_office": null,
  "prospective_department": null,
  "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
    }
  },
  "attachments": [
      {
          "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
          "url": "https://prod-heroku.s3.amazonaws.com/...",
          "type": "offer_packet",
          "created_at": "2020-09-27T18:45:27.137Z"
      }
  ]
}

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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
from_stage_id Yes integer The ID of the job stage this application is currently in.
to_stage_id Yes integer The ID of the job stage this application should be moved to.


See noteworthy response attributes.

PATCH: Convert Prospect To Candidate

curl -X PATCH 'https://harvest.greenhouse.io/v1/applications/{id}/convert_prospect'
-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": 123456,
  "initial_stage_id": 234567
}

The above returns a JSON response, structured like this:

{
  "success": true,
  "old_application_id": 1234321,
  "new_application_id": 43234323,
  "new_job_id": 123456,
  "new_stage_id": 234567
}

Converts a prospect application to a candidate on a job. If a non-prospect application is provided, an error will be returned.

HTTP Request

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
job_id Yes integer The ID of the job this prospect will become a candidate on.
initial_stage_id No integer The 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

POST: Add Attachment to Application

curl -X POST 'https://harvest.greenhouse.io/v1/applications/{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.s3.amazonaws.com/...",
  "type": "resume",
  "content_type": "application/pdf"
}

Post an attachment to an application by the application id.

HTTP Request

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
filename Yes string Name of the file
type Yes string One of: ["resume", "cover_letter", "other", "take_home_test", "offer_letter", "signed_offer_letter"]. For type take_home_test, there must be an outstanding test on the application. For type offer_letter, there must be an existing offer on the application, and this action will retrigger the approvals process. For type signed_offer_letter, there must be an approved, sent offer letter.
content No string Base64 encoded content of the attachment (if you are providing content, you do not need to provide url). String must be UTF-8 encoded.
url No string Url of the attachment (if you are providing the url, you do not need to provide the content.) Please note, shareable links from cloud services such as Google Drive will result in a corrupted file. Please use machine accessbile URLs.
visibility No string One of: ["public", "private", "admin_only"]. This only applies when attachment type is "other", and will be ignored for all other attachment types. If not supplied, type "other" documents will default to admin_only. Resumes, cover letters, and take home tests will always be public. Offer letters and signed offer letters will always be private.
content_type Yes* string The 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 required for when uploading a document unless you are uploading using a URL.

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"
    }
  ],
  "job_post_id": 123,
  "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"
    }
  ],
  "prospective_office": null,
  "prospective_department": null,
  "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
    }
  },
  "attachments": [
      {
          "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
          "url": "https://prod-heroku.s3.amazonaws.com/...",
          "type": "offer_packet",
          "created_at": "2020-09-27T18:45:27.137Z"
      }
  ]
}

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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
start_date No* string The start_date of the employee. Must be in the format YYYY-MM-DD
opening_id No integer An 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_id No integer The 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"
    }
  ],
  "job_post_id": 456,
  "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."
    }
  ],
  "prospective_office": null,
  "prospective_department": null,
  "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"
    }
  },
  "attachments": [
      {
          "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
          "url": "https://prod-heroku.s3.amazonaws.com/...",
          "type": "offer_packet",
          "created_at": "2020-09-27T18:45:27.137Z"
      }
  ]
}

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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
rejection_reason_id No integer The ID of the reason why this application was rejected.
notes No string Notes on why this application was rejected. These will be added to the activity feed.
rejection_email No hash An email will be sent to the candidate notifying them of this rejection.
rejection_email.send_email_at No string The rejection email will be delayed until this time. The On-Behalf-Of user's time zone will be used for scheduling the email.
rejection_email.email_template_id Yes, if sending rejection_email string The template to use for the rejection email. Template must be an organization wide email template.

PATCH: Update Rejection Reason

curl -X PATCH '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
}

The above returns a JSON response, structured like this: json { "id": 12345, "message": "Rejection reason updated to 815 (Higher Salary Offer Made)", "success": true }

This endpoint updates the rejection reason on a currently rejected application. An application in any other state will return an error. The rejection reason id may be either a custom rejection reason for your organization or a Greenhouse default rejection reason.

HTTP Request

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

URL parameters

Parameter Description
id ID of the application to update

JSON Body Parameters

Parameter Required Description
rejection_reason_id yes The ID of the new rejection reason

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"
    }
  ],
  "job_post_id": 123,
  "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"
    }
  ],
  "prospective_office": null,
  "prospective_department": null,
  "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"
    }
  },
  "attachments": [
      {
          "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
          "url": "https://prod-heroku.s3.amazonaws.com/...",
          "type": "offer_packet",
          "created_at": "2020-09-27T18:45:27.137Z"
      }
  ]

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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

URL parameters

Parameter Description
id ID 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

Attribute Description
id The approval's unique identifier
offer_id The specific offer for this approval. This will be empty for job approvals.
sequential true or false based on whether the groups in this flow must approve sequentially
version The specific version of this flow.
approval_type One of 'open_job,' 'offer_job' or 'offer_candidate.' open_job refers to approval flows to start recruiting on a job. offer_job refers to approval flows to make offers on a job. offer_candidate refers to approval flows for a candidate offer.
approval_status one of 'pending', 'approved', or 'rejected'
job_id The job for which approval is configured. This always has a value.
requested_by_user_id The 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

Parameter Description
id The 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

Parameter Description
id The 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

Header Description
On-Behalf-Of ID 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

Parameter Description
id The ID of the user whose pending approvals we want.

Querystring Parameters

Parameter Description
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

Attribute Description
status This is either "waiting" or "due" for pending approvals
approver_group_id This 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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes. Must have access to the approval flow.

URL Parameters

Parameter Description
approver_group_id The approver group in which we are replacing an approver.

Input JSON Parameters

Parameter Description
remove_user_id The user id of the approver to be removed.
add_user_id The user id of the new approver. Must have access to this approval flow.

Noteworthy Output JSON Parameters

Parameter Description
approval_flow_id The 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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes. Must have access to the approval flow.

URL Parameters

Parameter Description
job_id We will replace the approval flow on this job.

Input JSON Parameters

Parameter Description
approval_type Required. 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_id Optional. 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.
sequential Required. Accepts boolean true or false.
approver_groups The 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_required Required. 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.
approvers Must 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": "Customer Success Representative",
    "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": null,
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/...",
            "type": "offer_packet",
            "created_at": "2020-09-27T18:45:27.137Z"
        }
    ],
    "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"
    },
    "can_email": true,
    "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"
                }
            ],
            "job_post_id": 123,
            "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"
                }
            ],
            "prospective_office": null,
            "prospective_department": null,
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            },
            "attachments": [
                {
                    "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
                    "url": "https://prod-heroku.s3.amazonaws.com/...",
                    "type": "offer_packet",
                    "created_at": "2020-09-27T18:45:27.137Z"
                }
            ]
        },
        {
            "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"
                }
            ],
            "job_post_id": 456,
            "status": "active",
            "current_stage": {
                "id": 2966800,
                "name": "Face to Face"
            },
            "answers": [],
            "prospective_office": null,
            "prospective_department": null,
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            },
            "attachments": []
        }
    ],
    "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"
        }
    ],
    "linked_user_ids": [
        989604
    ],
    "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

Attribute Description
id The candidate's unique identifier
company The company at which the candidate currently works
title The candidate's current title
is_private Whether the candidate is private or not. One of: ["true", "false"]
application_ids Array of application IDs associated with this candidate. Can contain none, one, or several application IDs.
phone_numbers[].type One of: ["home", "work", "mobile", "skype", "other"]
addresses[].type One of: ["home", "work", "other"]
email_addresses[].type One of: ["personal", "work", "other"]
website_addresses[].type One of: ["personal", "company", "portfolio", "blog", "other"]
recruiter The recruiter user who is responsible for this candidate.
coordinator The coordinator user who is responsible for this candidate.
attachments[].type One of: ["resume", "cover_letter", "offer_packet", "offer_letter", "take_home_test", "other"]
attachments[].url URLs expire in 7 days.
custom_fields Contains 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_fields This 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.
linked_user_ids If the candidate is an internal applicant, this returns the Greenhouse user ID of the candidate.
photo_url Note: this field has been removed from Greenhouse and will always be null. For backwards compatibility, the field will remain in API payloads

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": "Customer Success Representative",
    "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": null,
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/...",
            "type": "offer_packet",
            "created_at": "2020-09-27T18:45:27.137Z"
        }
    ],
    "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,
    "can_email": true,
    "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"
                }
            ],
            "job_post_id": 123,
            "status": "active",
            "current_stage": null,
            "answers": [],
            "prospective_office": null,
            "prospective_department": null,
            "prospect_detail": {
                "prospect_pool": {
                    "id": 224,
                    "name": "Cold Outreach: Sourced"
                },
                "prospect_stage": {
                    "id": 817,
                    "name": "Contacted"
                },
                "prospect_owner": {
                    "id": 92120,
                    "name": "Greenhouse Admin"
                }
            },
            "attachments": [
                {
                    "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
                    "url": "https://prod-heroku.s3.amazonaws.com/...",
                    "type": "offer_packet",
                    "created_at": "2020-09-27T18:45:27.137Z"
                }
            ]
        },
        {
            "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": [],
            "prospective_office": null,
            "prospective_department": null,
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            },
            "attachments": []
        }
    ],
    "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"
        }
    ],
    "linked_user_ids": [
            989604
    ],
    "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

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
*page A cursor for use in pagination. Returns the n-th chunk of per_page objects.
*skip_count If true, the performance of retrieving candidates will improve. This will remove last from the link response header.
created_before Return only candidates that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_after Return only candidates that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_before Return only candidates that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_after Return only candidates that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.
job_id Only returns candidates who have applied to the specified job. Prospects on the job are not included.
email If 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_ids If 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": "Customer Success Representative",
    "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": null,
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/...",
            "type": "offer_packet",
            "created_at": "2020-09-27T18:45:27.137Z"
        }
    ],
    "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"
    },
    "can_email": true,
    "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"
                }
            ],
            "job_post_id": 123,
            "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"
                }
            ],
            "prospective_office": null,
            "prospective_department": null,
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            },
            "attachments": [
                {
                    "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
                    "url": "https://prod-heroku.s3.amazonaws.com/...",
                    "type": "offer_packet",
                    "created_at": "2020-09-27T18:45:27.137Z"
                }
            ]
        },
        {
            "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"
                }
            ],
            "job_post_id": 456,
            "status": "active",
            "current_stage": {
                "id": 2966800,
                "name": "Face to Face"
            },
            "answers": [],
            "prospective_office": null,
            "prospective_department": null,
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            },
            "attachments": []
        }
    ],
    "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"
        }
    ],
    "linked_user_ids": [
            989604
    ],
    "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

Parameter Description
id The 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

Header Description
On-Behalf-Of ID 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": "Customer Success Representative",
  "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": "Customer Success Representative",
      "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": null,
      "attachments": [
          {
              "filename": "John_Locke_Offer_Packet_09_28_2017.pdf",
              "url": "https://prod-heroku.s3.amazonaws.com/...",
              "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,
      "can_email": true,
      "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"
                  }
              ],
              "job_post_id": 123,
              "status": "active",
              "current_stage": {
                  "id": 2966800,
                  "name": "Face to Face"
              },
              "answers": [],
              "prospective_office": null,
              "prospective_department": null,
              "prospect_detail": {
                  "prospect_pool": null,
                  "prospect_stage": null,
                  "prospect_owner": null
              },
              "attachments": [
                  {
                      "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
                      "url": "https://prod-heroku.s3.amazonaws.com/...",
                      "type": "offer_packet",
                      "created_at": "2020-09-27T18:45:27.137Z"
                  }
              ]
          }
      ],
      "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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
first_name No string The candidate's first name
last_name No string The candidate's last name
company No string The candidate's company
title No string The candidate's title
is_private Whether the candidate is private or not. One of: ["true", "false"]
phone_numbers[] No phone_number Array of phone numbers. Passing an empty array will clear all.
addresses[] No address Array of addresses. Passing an empty array will clear all.
email_addresses[] No email_address Array of email addresses. Passing an empty array will clear all.
website_addresses[] No website_address Array of website addresses. Passing an empty array will clear all.
social_media_addresses[] No social_media_address Array of social media addresses. Passing an empty array will clear all.
tags[] No string Array of tags as strings. Passing an empty array will clear all.
custom_fields[] No custom_field Array of hashes containing new custom field values. Passing an empty array does nothing.
recruiter No Hash An object representing the candidate's new recruiter
recruiter[id] No Integer The ID of the new recruiter - either id or email must be present.
recruiter[email] No String The email of the new recruiter - either id or email must be present.
coordinator No Hash An object representing the candidate's new coordinator
coordinator[id] No Integer The ID of the new coordinator - either id or email must be present.
coordinator[email] No String The 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.

Parameter Required for Description
id all The custom field id for this particular custom field. One of this or name_key is required.
name_key all The 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.
value all The 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.
unit currency This 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_value n/a When 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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
filename Yes string Name of the file
type Yes string One of: ["resume", "cover_letter", "admin_only"]
content No string Base64 encoded content of the attachment (if you are providing content, you do not need to provide url). String must be UTF-8 encoded.
url No string Url of the attachment (if you are providing the url, you do not need to provide the content.) Please note, shareable links from cloud services such as Google Drive will result in a corrupted file. Please use machine accessbile URLs.
content_type Yes* string The 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 required for when uploading a document unless you are uploading using a URL.

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": "Customer Success Representative",
  "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": "Customer Success Representative",
    "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,
    "can_email": true,
    "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"
                }
            ],
            "job_post_id": 123,
            "status": "active",
            "current_stage": {
                "id": 1355395,
                "name": "Application Review"
            },
            "answers": [],
            "prospective_office": null,
            "prospective_department": null,
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            },
            "attachments": []
        },
        {
            "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 "
                }
            ],
            "job_post_id": 456,
            "status": "active",
            "current_stage": {
                "id": 1579673,
                "name": "Application Review"
            },
            "answers": [],
            "prospective_office": null,
            "prospective_department": null,
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            },
            "attachments": []
        }
    ],
    "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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
first_name Yes string The candidate's first name
last_name Yes string The candidate's last name
company No string The candidate's company
title No string The candidate's title
phone_numbers[] No phone_number Array of phone numbers. Passing an empty array will clear all.
addresses[] No address Array of addresses. Passing an empty array will clear all.
email_addresses[] No email_address Array of email addresses. Passing an empty array will clear all.
website_addresses[] No website_address Array of website addresses. Passing an empty array will clear all.
social_media_addresses[] No social_media_address Array of social media addresses. Passing an empty array will clear all.
educations No Array An array of education records. See Add Education for parameters.
employments No Array An array of employment records. See Add Employment for parameters.
tags[] No string Array of tags as strings. Passing an empty array will clear all.
custom_fields[] No custom_field Array of hashes containing new custom field values. Passing an empty array does nothing.
recruiter No Object An object representing the candidate's recruiter
recruiter[id] No Integer The ID of the recruiter - either id or email must be present.
recruiter[email] No String The email of the recruiter - either id or email must be present.
coordinator No Object An object representing the candidate's coordinator
coordinator[id] No Integer The ID of the coordinator - either id or email must be present.
coordinator[email] No String The email of the coordinator - either id or email must be present.
custom_fields No Array Array of custom field value objects - See "Custom Field Parameters" under Edit candidate for parameters.
activity_feed_notes No Array An array of activity feed objects. See Add Note for parameters.
applications Yes Array An array of application objects. At least one required. See Add Application for parameters.

See noteworthy response attributes.

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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
user_id Yes integer The ID of the user creating the note
body Yes string Note body
visibility* Yes string One 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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
user_id Yes integer The ID of the user creating the note
to Yes string This is a free text field that is meant to be an e-mail address. E-mail format will not be validated.
from Yes string This is a free text field that is meant to be an e-mail address. E-mail format will not be validated.
cc No Array This is meant to be an array of e-mail addresses. E-mail format will not be validated.
subject Yes string The subject line of the e-mail.
body Yes string The 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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
school_id No integer The ID of the college attended; from the GET schools endpoint
discipline_id No integer The ID of the discipline of the candidate's education; from the GET disciplines endpoint.
degree_id No integer The type of degree received; from the GET degrees endpoint
start_month No integer The month the candidate began attendance. Must be between 1-12.
start_year No integer The year the candidate began attendance. Must be between 1900-2100.
start_date No DateTime The date the candidate began attendance. Timestamp must be in in ISO-8601 format.*
end_month No integer The month the candidate finished attendance. Must be between 1-12.
end_year No integer The year the candidate finished attendance. Must be between 1900-2100.
end_date No DateTime The 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

Header Description
On-Behalf-Of ID 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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
company_name Yes String A free text field indicating an employer's name
title Yes String A free text field indicating the candidate's title while at the employer.
start_date Yes DateTime The date the candidate began at employer. Timestamp must be in in ISO-8601 format.*
end_date No DateTime The 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

Header Description
On-Behalf-Of ID 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": "Customer Success Representative",
  "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": "Customer Success Representative",
  "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,
  "can_email": true,
  "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": [],
      "job_post_id": null,
      "status": "active",
      "current_stage": null,
      "answers": [],
      "prospective_office": {
          "primary_contact_user_id": null,
          "parent_id": null,
          "name": "New York",
          "location": {
              "name": "New York, NY"
          },
          "id": 59213,
          "external_id": null,
          "child_ids": []
      },
      "prospective_department": {
          "parent_id": null,
          "name": "Marketing",
          "id": 9024,
          "external_id": null,
          "child_ids": []
      },
      "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": {
        "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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
first_name Yes string The prospect's first name
last_name Yes string The prospect's last name
company No string The prospect's company
title No string The prospect's title
phone_numbers[] No phone_number Array of phone numbers. Passing an empty array will clear all.
addresses[] No address Array of addresses. Passing an empty array will clear all.
email_addresses[] No email_address Array of email addresses. Passing an empty array will clear all.
website_addresses[] No website_address Array of website addresses. Passing an empty array will clear all.
social_media_addresses[] No social_media_address Array of social media addresses. Passing an empty array will clear all.
tags[] No string Array of tags as strings. Passing an empty array will clear all.
custom_fields[] No custom_field Array of hashes containing new custom field values. Passing an empty array does nothing.
recruiter No Object An object representing the prospect's recruiter
recruiter[id] No Integer The ID of the recruiter - either id or email must be present.
recruiter[email] No String The email of the recruiter - either id or email must be present.
coordinator No Object An object representing the prospect's coordinator
coordinator[id] No Integer The ID of the coordinator - either id or email must be present.
coordinator[email] No String The email of the coordinator - either id or email must be present.
custom_fields No Array Array of custom field value objects - See "Custom Field Parameters" under Edit candidate for parameters.
activity_feed_notes No Array An array of activity feed objects. See Add Note for parameters.
application No Hash Unlike a candidate application, a prospect application can contain zero or multiple job IDs because a prospect in Greenhouse Recruiting can be attached to zero or many jobs. If your request doesn’t contain an application object, the prospect will be created with a single, jobless application. If your request includes an application object, the source_id, referrer, custom_fields, and attachments parameters must match the format of the Add Application endpoint.
application[job_ids] No Array This 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": null,
    "attachments": [
        {
            "filename": "John_Locke_Offer_Packet_09_28_2017.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/...",
            "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,
    "can_email": true,
    "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"
                }
            ],
            "job_post_id": 123,
            "status": "active",
            "current_stage": {
                "id": 1567309,
                "name": "Application Review"
            },
            "answers": [],
            "prospective_office": null,
            "prospective_department": null,
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            },
            "attachments": [
                {
                    "filename": "John_Locke_Offer_Packet_09_27_2017.pdf",
                    "url": "https://prod-heroku.s3.amazonaws.com/...",
                    "type": "offer_packet",
                    "created_at": "2020-09-27T18:45:27.137Z"
                }
            ]
        }
    ],
    "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.

HTTP Request

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

Querystring Parameters

Parameter Required Type Description
fields Yes comma-delimited string The 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, 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": "Customer Success Representative",
    "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/...",
            "type": "resume"
        },
         {
            "filename": "Justin Locke cover leter.pdf",
            "url": "https://prod-heroku.s3.amazonaws.com/...",
            "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,
    "can_email": true,
    "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"
                }
            ],
            "job_post_id": 123,
            "status": "active",
            "current_stage": {
                "id": 1567309,
                "name": "Application Review"
            },
            "answers": [],
            "prospective_office": null,
            "prospective_department": null,
            "prospect_detail": {
                "prospect_pool": null,
                "prospect_stage": null,
                "prospect_owner": null
            },
            "attachments": [
                {
                    "filename": "Justin Locke resume.pdf",
                    "url": "https://prod-heroku.s3.amazonaws.com/...",
                    "type": "resume"
                },
                {
                    "filename": "Justin Locke cover leter.pdf",
                    "url": "https://prod-heroku.s3.amazonaws.com/...",
                    "type": "cover_letter"
                }
            ]
        }
    ],
    "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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
primary_candidate_id Yes integer The id of the first candidate that will be merged. This candidate will also be the result of the merge.
duplicate_candidate_id Yes integer The 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

Attribute Description
id The close reason's unique identifier. This is the ID that would be used in POST or PATCH statements involving close reasons.
name The 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": "Seniority Level",
  "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",
  "description": "Seniority of this role",
  "expose_in_job_board_api": true,
  "api_only": false,
  "offices": [
    {
      "id": 11915,
      "name": "New York",
      "location": {
        "name": "New York, New York, United States"
      },
      "primary_contact_user_id": null,
      "parent_id": null,
      "parent_office_external_id": null,
      "child_ids": [],
      "child_office_external_ids": [],
      "external_id": null
    }
  ],
  "departments": [],
  "template_token_string": "{{SENIORITY}}",
  "custom_field_options": [
    {
      "id": 123,
      "name": "Junior",
      "priority": 1,
      "external_id": "jr"
    },
    {
      "id": 234,
      "name": "Senior",
      "priority": 2,
      "external_id": null
    }
  ]
}

Noteworthy attributes

Attribute Description
id The custom field's unique identifier
name The field's name in Greenhouse
active Boolean value which is false if the custom field has been deleted, true otherwise.
field_type One of job, candidate, application, offer, opening, rejection_question, referral_question, or user_attribute. This is also included in the URL as an argument, which will return only custom fields that match the given type.
priority Numeric field used for ordering in Greenhouse.
value_type One of short_text, long_text, yes_no, single_select, multi_select, currency, currency_range, number, number_range, date, url, or user. For the user_attribute field type, only the following value types are supported currently: single_select, multi_select, yes_no, and user
private Boolean value to say if this field is private in Greenhouse.
required The object this field exists on can not be saved if this value is not set.
require_approval Only applicable to job and opening custom fields, changes to this fields requires an approval flow in Greenhouse to be re-done.
trigger_new_version Only applicable to offer custom fields, changes to this field creates a new offer version.
name_key Listed 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_options For single_select and multi_select field_types, this is the list of options for that select.
custom_field_options.priority Numeric value used for ordering the custom field options.
custom_field_options.external_id String value, the external_id for the custom field option
description The custom field's description
expose_in_job_board_api Boolean. Only relevant for Job custom fields. If true, then the field will be shown in the Job Board API.
api_only Boolean. Only relevant for Job custom fields. If true, this custom field can only be edited from the API.
offices Only relevant for Job, Opening, and Offer custom fields. If this custom field only applies to a subset of offices, then this list contains each office. Otherwise, if the list is empty, it applies to all offices.
departments Only relevant for Job, Opening, and Offer custom fields. If this custom field only applies to a subset of departments, then this list contains each department. Otherwise, if the list is empty, it applies to all departments.
template_token_string Token string used in email and offer document templates

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",
    "description": "Field description",
    "expose_in_job_board_api": false,
    "api_only": false,
    "offices": [],
    "departments": [],
    "template_token_string": "{{FIELD1}}",
    "custom_field_options": [
      {
        "id": 123,
        "name": "Name One",
        "priority": 1,
        "external_id": "name-one"
      },
      {
        "id": 234,
        "name": "Name Two",
        "priority": 2,
        "external_id": null
      }
    ]
  }
]

HTTP Request

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

URL parameters

Parameter Description
*field_type Returns 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, user_attribute.

Querystring parameters

Parameter Description
include_inactive When 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",
  "description": "Field description",
  "expose_in_job_board_api": false,
  "api_only": false,
  "offices": [],
  "departments": [],
  "template_token_string": "{{FIELD1}}",
  "custom_field_options": [
    {
      "id": 123,
      "name": "Name One",
      "priority": 1,
      "external_id": "name-one"
    },
    {
      "id": 234,
      "name": "Name Two",
      "priority": 2,
      "external_id": null
    }
  ]
}

HTTP Request

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

URL Parameters

Parameter Description
id The 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,
  "external_id": "option-a"
}

Noteworthy attributes

Attribute Description
priority Numeric field used for ordering in Greenhouse.
external_id String field, the external_id for the custom field option.

POST: Create Custom Field

curl -X POST 'https://harvest.greenhouse.io/v1/custom_fields/'
-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": "Custom Field Name",
  "field_type": "application",
  "value_type": "single_select",
  "private": false,
  "generate_email_token": true,
  "required": false,
  "require_approval": false,
  "expose_in_job_board_api": true,
  "api_only": false,
  "trigger_new_version": false,
  "office_ids": [123, 456],
  "department_ids": [567, 890],
  "custom_field_options": [
    {
      "name": "Name One",
      "priority": 1,
      "external_id": "name-one"
    },
    {
      "name": "Name Two",
      "priority": 2,
      "external_id": null
    }
  ]
}

If successful, the above command returns a 201 response code along with a JSON representation of the newly created custom field. The JSON structure looks 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",
    "description": "Field description",
    "expose_in_job_board_api": false,
    "api_only": false,
    "offices": [],
    "departments": [],
    "template_token_string": "{{FIELD1}}",
    "custom_field_options": [
      {
        "id": 123,
        "name": "Name One",
        "priority": 1,
        "external_id": "name-one"
      },
      {
        "id": 234,
        "name": "Name Two",
        "priority": 2,
        "external_id": null
      }
    ]
  }
]

HTTP Request

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

JSON Body Parameters

Attribute Type Required Description
name string yes The field's name in Greenhouse
description string no The field's description in Greenhouse
field_type string yes One of job, candidate, application, offer, opening, rejection_question, referral_question, user_attribute.
value_type string yes One of short_text, long_text, yes_no, single_select, multi_select, currency, currency_range, number, number_range, date, url, or user. For the user_attribute field type, only the following value types are supported currently: single_select, multi_select, yes_no, and user
private boolean no Boolean value to say if this field is private in Greenhouse. Defaults to false if not provided for non-offer custom fields. For offer custom fields, private is always true.
required boolean no Boolean value to determine if this field must be filled out in order to save the custom field. Only used for job, offer, and opening type custom fields. Defaults to false.
require_approval boolean no Boolean value to determine if changes to this custom field triggers re-approvals. Only used for job and opening custom fields. Defaults to false.
trigger_new_version boolean no Boolean value to determine if changes to this field triggers the automatic creation of a new offer version. Only used in offer custom fields. Defaults to false.
expose_in_job_board_api boolean no Boolean value to determine if this custom field and its value will be provied in the Job Board API response for this job. These fields are included in the metadata section of the Job Board API response. Only used in job custom fields. Defaults to false.
api_only boolean no Boolean value to determine if updates to this custom field may only be made via Harvest. Only used in job custom fields. Defaults to false. If this feature is not available for your organization, attempting to create a field with this set to true will return an API Error.
office_ids Array of integers no If included, this custom field is only displayed on objects associated with these offices. This is only used for job, opening, and offer custom fields. If not included, custom field will be shown for all offices.
department_ids Array of integers no If included, this custom field is only displayed on objects associated with these departments. This is only used for job, opening, and offer custom fields. If not included, custom field will be shown for all departments.
custom_field_options array of Custom Field Options yes for some field_type For single_select and multi_select field_types, this is the list of options for that select.
custom_field_options.name string yes The name of the new custom field option.
custom_field_options.priority integer yes Numeric value used for ordering the custom field options.
custom_field_options.external_id string no The external_id for the custom field. Used for integrating with external HRIS.
generate_email_token boolean no If this is sent as true, a default template_token_string will be generated for the new Custom Field.

PATCH: Update Custom Field

This endpoint updates an existing custom field.

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

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

{
  "name": "New Name",
  "description": "New description",
  "private": false,
  "template_token_string": "token123"
}

If the update is successful, the above command returns JSON structured like this:

[
  {
    "id": 123456,
    "name": "New Name",
    "active": true,
    "field_type": "job",
    "priority": 1,
    "value_type": "single_select",
    "private": false,
    "required": false,
    "require_approval": true,
    "trigger_new_version": false,
    "name_key": "custom_field_name",
    "description": "New description",
    "expose_in_job_board_api": false,
    "api_only": false,
    "offices": [],
    "departments": [],
    "template_token_string": "{{token123}}",
    "custom_field_options": [
      {
        "id": 123,
        "name": "Name One",
        "priority": 1,
        "external_id": "name-one"
      },
      {
        "id": 234,
        "name": "Name Two",
        "priority": 2,
        "external_id": null
      }
    ]
  }
]

HTTP Request

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

URL Parameters

Parameter Description
id The ID of the custom field to update

JSON Body Parameters

This endpoint accepts the same JSON body parameters as the Create Custom Field endpoint. There is one exception - instead of the generate_email_token field which is used during creation, the template_token_string field can be used to set or change the template token on an existing custom field.

Attribute Type Required Description
template_token_string string no Sets the template token which is used in email and offer document templates.

DELETE: Delete Custom Field

This endpoint deletes a custom field. Note that custom fields are soft-deleted in order to maintain historical data. Soft-deleted custom fields will be hidden to users but will continue to be returned in the API with their active flag set to false.

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

If the deletion is successful, the above command returns JSON structured like this:

{
  "success": "Custom Field ID 12345 has been deleted."
}

HTTP Request

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

URL Parameters

Parameter Description
id The ID of the custom field to delete

GET: List Custom Field Options

curl '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 returns JSON structured like this:

[
  {
    "id": 123456,
    "name": "Option A",
    "priority": 0,
    "external_id": "option-a"
  },
  {
    "id": 123457,
    "name": "Option B",
    "priority": 1,
    "external_id": "option-b"
  },
  {
    "id": 123458,
    "name": "Option C",
    "priority": 2,
    "external_id": null
  }
]

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

Parameter Description
type One 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, "external_id": "3z84k11"},
    {"name": "Option B", "priority": 6, "external_id": "bmlpk1"},
    {"name": "Option C", "priority": 7, "external_id": "32290"}
  ]
}

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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
options Yes array An array of one or many new custom field options.
name Yes string The 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.
priority Yes integer This is used to order the custom fields in Greenhouse.
external_id No string The external_id for the custom field. Used for integrating with external HRIS.


**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,
      "external_id": "3z84k11"
    },
    {
      "id": 234,
      "name": "Option B",
      "priority": 6,
      "external_id": null
    },
    {
      "id": 345,
      "name": "Option C",
      "priority": 7,
      "external_id": "32290"
    }
  ]
}

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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
options Yes array An array of one or many new custom field options.
id Yes integer The ID of the custom field option that will be updated.
name No string If 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.
priority No integer If included, The custom field option with this ID will be updated with this value.
external_id No string If included, the custom field option will update its external_id with this value. Passing null will clear the external_id.


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

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
option_ids Yes array An 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.

Demographic Data

Demographic questions and answers submitted during the application process. For more information on Greenhouse Inclusion, please visit https://www.greenhouse.io/inclusion.

The Demographic Question Set object

{
  "id": 1991,
  "title": "Question Set",
  "description": "<p>Questions for candidates</p>",
  "active": true
}

Noteworthy attributes

Attribute Description
id The demographic question set's unique identifier
title The title of the demographic question set
description The demographic question set's description. This is a rich text field which may contain HTML.
active If false, the demographic question set has been deleted.

The Demographic Question object

{
  "id": 123,
  "active": true,
  "demographic_question_set_id": 456,
  "name": "What is your favorite color?",
  "translations": [
    {
      "language": "en",
      "name": "What is your favorite color?"
    }
  ],
  "required": true,
  "answer_type": "multi_value_multi_select"
}

Noteworthy attributes

Attribute Description
id The demographic question's unique identifier
demographic_question_set_id The demographic question set that this belongs to
name The question text
translations.language Translations have been deprecated but are kept for backwards compatibility. Only en (English) is supported at this time.
translations.name Translations have been deprecated but are kept for backwards compatibility. This value will be the same as name above.
active If false, the question has been deleted.
required If true, the question must be filled out by the applicant.
answer_type The type of answer that can be provided for the question. Value will be either multi_value_single_select or multi_value_multi_select.

The Demographic Answer Option object

{
  "id": 456,
  "free_form": false,
  "active": true,
  "name": "Blue",
  "demographic_question_id": 123,
  "translations": [
    {
      "language": "en",
      "name": "Blue"
    }
  ]
}

Noteworthy attributes

Attribute Description
id The demographic answer option's unique identifier
name The answer option text
translations.language Translations have been deprecated but are kept for backwards compatibility. Only en (English) is supported at this time.
translations.name Translations have been deprecated but are kept for backwards compatibility. This value will be the same as name above.
active If false, the answer option has been deleted.
free_form If true, the answer option allows free-form user input.
demographic_question_id The demographic question for which the answer option belongs to.

The Demographic Answer object

{
  "id": 51,
  "free_form_text": "12am",
  "application_id": 107594341,
  "demographic_question_id": 25,
  "demographic_answer_option_id": 106,
  "created_at": "2019-04-29T18:46:03.707Z",
  "updated_at": "2019-04-29T18:46:03.707Z"
}

Noteworthy attributes

Attribute Description
id The demographic answer's unique identifier
free_form_text If the selected answer option is free-form, this is the value given by the user. Otherwise null.
application_id The application for which the demographic question was answered
demographic_question_id The demographic question which was answered.
demographic_answer_option_id The demographic answer option which was selected.

GET: List Demographic Question Sets

List all of an organization's demographic question sets.

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

The above command returns JSON structured like this:

[
  {
    "id": 1991,
    "title": "Question Set A",
    "description": "<p>Questions for US candidates</p>",
    "active": true
  },
  {
    "id": 1992,
    "title": "Question Set B",
    "description": "<p>Questions for European candidates</p>",
    "active": true
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/demographics/question_sets

Querystring parameters

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.


See noteworthy response attributes.

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

GET: Retrieve Demographic Question Set

Retrieve a demographic question set by its id.

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

The above command returns JSON structured like this:

{
  "id": 1991,
  "title": "Question Set",
  "description": "<p>Questions for candidates</p>",
  "active": true
}

HTTP Request

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

URL Parameters

Parameter Description
id ID of the demographic question set you want to retrieve.


See noteworthy response attributes.

GET: List Demographic Questions

List all of an organization's demographic questions.

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

The above command returns JSON structured like this:

[
  {
    "id": 123,
    "active": true,
    "demographic_question_set_id": 456,

    "name": "What is your favorite color?",
    "translations": [
      {
        "language": "en",
        "name": "What is your favorite color?"
      }
    ],
    "required": true
  },
  {
    "id": 897,
    "active": true,
    "demographic_question_set_id": 555,
    "name": "Pizza or pasta?",
    "translations": [
      {
        "language": "en",
        "name": "Pizza or pasta?"
      }
    ],
    "required": false
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/demographics/questions

Querystring parameters

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.


See noteworthy response attributes.

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

GET: List Demographic Questions For Demographic Question Set

List all of the demographic questions for a demographic question set.

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

The above command returns JSON structured like this:

[
  {
    "id": 123,
    "active": true,
    "demographic_question_set_id": 456,
    "name": "What is your favorite color?",
    "translations": [
      {
        "language": "en",
        "name": "What is your favorite color?"
      }
    ],
    "required": true
  },
  {
    "id": 897,
    "active": true,
    "demographic_question_set_id": 555,
    "name": "Pizza or pasta?",
    "translations": [
      {
        "language": "en",
        "name": "Pizza or pasta?"
      }
    ],
    "required": false
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/demographics/question_sets/{id}/questions

URL Parameters

Parameter Description
id ID of the demographic question set for which you want to retrieve demographic questions

Querystring parameters

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.


See noteworthy response attributes.

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

GET: Retrieve Demographic Question

Retrieve a demographic question by its id.

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

The above command returns JSON structured like this:

{
  "id": 123,
  "active": true,
  "demographic_question_set_id": 456,
  "name": "What is your favorite color?",
  "translations": [
    {
      "language": "en",
      "name": "What is your favorite color?"
    }
  ],
  "required": true
}

HTTP Request

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

URL Parameters

Parameter Description
id ID of the demographic question you want to retrieve.


See noteworthy response attributes.

GET: List Demographic Answer Options

List all of an organization's demographic answer options.

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

The above command returns JSON structured like this:

[
  {
    "id": 456,
    "free_form": false,
    "active": true,
    "name": "Blue",
    "demographic_question_id": 123,
    "translations": [
      {
        "language": "en",
        "name": "Blue"
      }
    ]
  },
  {
    "id": 789,
    "free_form": true,
    "active": true,
    "name": "Other",
    "demographic_question_id": 123,
    "translations": [
      {
        "language": "en",
        "name": "Other"
      }
    ]
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/demographics/answer_options

Querystring parameters

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.


See noteworthy response attributes.

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

GET: List Demographic Answer Options For Demographic Question

List all of the demographic answer options for a demographic question.

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

The above command returns JSON structured like this:

[
  {
    "id": 456,
    "free_form": false,
    "active": true,
    "name": "Blue",
    "demographic_question_id": 123,
    "translations": [
      {
        "language": "en",
        "name": "Blue"
      }
    ]
  },
  {
    "id": 789,
    "free_form": true,
    "active": true,
    "name": "Other",
    "demographic_question_id": 123,
    "translations": [
      {
        "language": "en",
        "name": "Other"
      }
    ]
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/demographics/questions/{id}/answer_options

URL Parameters

Parameter Description
id ID of the demographic question for which you want to retrieve demographic answer options.

Querystring parameters

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.


See noteworthy response attributes.

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

GET: Retrieve Demographic Answer Option

Retrieve a demographic answer option by its id.

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

The above command returns JSON structured like this:

{
  "id": 456,
  "free_form": false,
  "active": true,
  "name": "Blue",
  "demographic_question_id": 123,
  "translations": [
    {
      "language": "en",
      "name": "Blue"
    }
  ]
}

HTTP Request

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

URL Parameters

Parameter Description
id ID of the demographic answer option you want to retrieve.


See noteworthy response attributes.

GET: List Demographic Answers

List all of an organization's demographic answers.

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

The above command returns JSON structured like this:

[
  {
    "id": 123,
    "free_form_text": "12am",
    "application_id": 787,
    "demographic_question_id": 25,
    "demographic_answer_option_id": 106,
    "created_at": "2019-04-29T18:46:03.707Z",
    "updated_at": "2019-04-29T18:46:03.707Z"
  },
  {
    "id": 456,
    "free_form_text": null,
    "application_id": 783,
    "demographic_question_id": 29,
    "demographic_answer_option_id": 109,
    "created_at": "2017-01-29T15:09:46.806Z",
    "updated_at": "2017-01-29T15:09:46.806Z"
  }
]

HTTP Request

GET https://harvest.greenhouse.io/v1/demographics/answers

Querystring parameters

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
*created_before Return only answers created before this timestamp. Timestamp must be in ISO-8601 format.
*created_after Return only answers created at or after this timestamp. Timestamp must be in ISO-8601 format.
*updated_before Return only answers updated before this timestamp. Timestamp must be in ISO-8601 format.
*updated_after Return only answers updated at or after this timestamp. Timestamp must be in ISO-8601 format.


See noteworthy response attributes.

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

GET: List Demographic Answers For Application

List all of the demographic answers for an application.

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

The above command returns JSON structured like this:

[
  {
    "id": 123,
    "free_form_text": "12am",
    "application_id": 787,
    "demographic_question_id": 25,
    "demographic_answer_option_id": 106,
    "created_at": "2019-04-29T18:46:03.707Z",
    "updated_at": "2019-04-29T18:46:03.707Z"
  },
  {
    "id": 456,
    "free_form_text": null,
    "application_id": 787,
    "demographic_question_id": 29,
    "demographic_answer_option_id": 109,
    "created_at": "2017-01-29T15:09:46.806Z",
    "updated_at": "2017-01-29T15:09:46.806Z"
  }
]

HTTP Request

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

URL Parameters

Parameter Description
id ID of the application for which you want to retrieve demographic answers.

Querystring parameters

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
*created_before Return only answers created before this timestamp. Timestamp must be in ISO-8601 format.
*created_after Return only answers created at or after this timestamp. Timestamp must be in ISO-8601 format.
*updated_before Return only answers updated before this timestamp. Timestamp must be in ISO-8601 format.
*updated_after Return only answers updated at or after this timestamp. Timestamp must be in ISO-8601 format.


See noteworthy response attributes.

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

GET: Retrieve Demographic Answer

Retrieve a demographic answer by its id.

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

The above command returns JSON structured like this:

{
  "id": 123,
  "free_form_text": "12am",
  "application_id": 787,
  "demographic_question_id": 25,
  "demographic_answer_option_id": 106,
  "created_at": "2019-04-29T18:46:03.707Z"
}

HTTP Request

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

URL Parameters

Parameter Description
id ID of the demographic answer you want to retrieve.


See noteworthy response attributes.

Departments

The department object

An organization's departments.

With render_as=list (default)

{
  "id": 12345,
  "name": "Technology",
  "parent_id": 12345,
  "parent_department_external_id": "parent-1",
  "child_ids": [
      34065,
      25908
  ],
  "child_department_external_ids": [
      "child-1",
      "child-2"
  ],
  "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

Attribute Description
id The department's unique identifier
name The department's name
external_id An arbitrary ID provided by an external source; does not map to another entity in Greenhouse.
parent_department_external_id The external_id of this department's parent.
parent_department_child_ids the external_ids of this department's children. Note the order of this array may not match the order of the child_ids array. If there are five children and none of them have parent ids, this array will contain five null indices.

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,
    "parent_department_external_id": "",
    "child_ids": [
        34065,
        25908
    ],
    "child_department_external_ids": [
        "child-1",
        "child-2"
    ],
    "external_id": "89076"
  },
  {
    "id": 67890,
    "name": "Administration",
    "parent_id": 54647,
    "parent_department_external_id": "parent-1",
    "child_ids": [],
    "child_department_external_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

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
*page A cursor for use in pagination. Returns the n-th chunk of per_page objects.
*skip_count If true, the performance of retrieving departments will improve. This will remove last from the link response header.
render_as This 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.
external_id If supplied, only return department(s) with that external ID.


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,
  "parent_department_external_ids": "",
  "child_ids": [
      34065,
      25908
  ],
  "child_department_external_ids": [
      "child-1",
      "child-2"
  ],
  "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

Parameter Description
id The ID of the department to retrieve

Querystring parameters

Parameter Description
render_as This 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,
  "parent_department_external_id": "",
  "child_ids": [
      34065,
      25908
  ],
  "child_department_external_ids": [
      "child-1",
      "child-2"
  ],
  "external_id": "EXTERNAL_ID_1234"
}

Edit a department's basic information.

HTTP Request

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
name Yes string The department's name. If included, this cannot be blank.
external_id* No string The 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"
}

or 

{
  "name": "A New Department",
  "external_parent_id": "parent-1",
  "external_id": "456454"
}

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

{
  "id": 34535,
  "name": "A New Department",
  "parent_id": 12345,
  "parent_department_external_ids": "parent-1",
  "child_ids": [],
  "child_department_external_ids": [],
  "external_id": "456454"
}

Create a new department

HTTP Request

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes. Must be a user who can create departments.

JSON Body Parameters

Parameter Required Type Description
name yes string The name of your new department. Must be less than 255 characters and unique within your organization.
parent_id* no number The 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_parent_id** no string The external id of the parent departments. This may be used instead of parent_id. Only one of this or parent_id may be populated. If both are included, it will raise an error.
external_id** no string The external_id for the office.

* - The tiered department feature is available only for customers with the Advanced or Expert 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 Expert 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 have a history/record of having a disability"
  },
  "submitted_at": "2017-01-29T15:09:46.806Z"
}

Noteworthy attributes

Attribute Description
application_id Application ID
candidate_id The ID of the candidate who is applying for the job associated with this application.
race See the EEOC Reference below
gender See the EEOC Reference below
veteran_status See the EEOC Reference below
disability_status See the EEOC Reference below
submitted_at The 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 have a history/record of having a disability
No, I don’t have a disability, or a history/record of having 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 have a history/record of having 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 have a history/record of having 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

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
*submitted_before Return only EEOC data submitted before this timestamp. Timestamp must be in ISO-8601 format.
*submitted_after Return 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 have a history/record of having 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

Parameter Description
id ID 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

Attribute Description
id The email template's unique identifier
type One 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
from The 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.
body The plain text body of the e-mail (may be null).
user The user this template belongs to. If null, this is an 'organization wide' template available to everyone.
html_body The 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

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
*page A cursor for use in pagination. Returns the n-th chunk of per_page objects.
*skip_count If true, the performance of retrieving email templates will improve. This will remove last from the link response header.
created_before Return only email templates that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_after Return only email templates that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_before Return only email templates that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_after Return 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

Parameter Description
id The 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,
        "custom_fields": {
            "employment_type": "Full-Time",
             "maximum_budget": "$81.5k"
    },
    "keyed_custom_fields": {
            "employment_type": {
            "name": "Time type",
            "type": "single_select",
            "value": "Full-Time"
            },
            "budget": {
            "name": "Maximum Budget",
            "type": "short_text",
            "value": "$81.5k"
            }
        }
    },
    {
        "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"
        },
        "custom_fields": {
            "employment_type": "Full-Time",
             "maximum_budget": "$81.5k"
    },
    "keyed_custom_fields": {
            "employment_type": {
            "name": "Time type",
            "type": "single_select",
            "value": "Full-Time"
            },
            "budget": {
            "name": "Maximum Budget",
            "type": "short_text",
            "value": "$81.5k"
            }
        }
    }
]

Noteworthy Attributes

Attribute Description
id The opening's unique identifier
opening_id This is a text string used to identify the opening. This is defined by the users and may be null.
status Either "open" or "closed"
opened_at This is the date and time this opening was opened.
closed_at This is when the opening was closed; usually via the opening being filled. This should be null for opened openings.
application_id The application that was used to fill this opening. This should only be set on a closed opening, null otherwise.
custom_fields These are the custom fields that are specific to openings. This index, along with keyed_custom_fields, may not be included if your organization does not have access to custom fields on openings.

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,
      "custom_fields": {
          "employment_type": "Full-Time",
          "maximum_budget": "$81.5k"
      },
      "keyed_custom_fields": {
          "employment_type": {
              "name": "Time type",
              "type": "single_select",
              "value": "Full-Time"
          },
          "budget": {
              "name": "Maximum Budget",
              "type": "short_text",
              "value": "$81.5k"
          }
      }
  },
  {
      "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"
      },
      "custom_fields": {
          "employment_type": "Full-Time",
          "maximum_budget": "$81.5k"
      },
      "keyed_custom_fields": {
          "employment_type": {
              "name": "Time type",
              "type": "single_select",
              "value": "Full-Time"
          },
          "budget": {
              "name": "Maximum Budget",
              "type": "short_text",
              "value": "$81.5k"
          }
      }
  }
]

List all of a job's openings

HTTP Request

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

URL Paramters

Parameter Description
job_id The ID of the job for which you want to retrieve openings.

Querystring Parameters

Parameter Description
status May 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,
    "custom_fields": {
        "employment_type": "Full-Time",
        "maximum_budget": "$81.5k"
    },
    "keyed_custom_fields": {
        "employment_type": {
            "name": "Time type",
            "type": "single_select",
            "value": "Full-Time"
        },
        "budget": {
            "name": "Maximum Budget",
            "type": "short_text",
            "value": "$81.5k"
        }
    }
}

Retrieve the information for a single opening.

HTTP Request

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

URL Parameters

Parameter Description
job_id The ID of the job for which you want to retrieve openings.
id The 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

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

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
ids yes Array An array of opening ids to delete. Important to note that these are not opening_id from the other endpoints, but the unique id identifier.

Notes: The v1 version of this endpoint has been deprecated because it allowed integrations to delete open or filled openings that were otherwise prevented by data validations in the Greenhouse Recruiting UI.

The v2 version of this endpoint only allows closed, unfilled openings to be deleted and respects data validation rules as they exist in Greenhouse Recruiting. When the v1 endpoint is deprecated, some integrations may experience errors if they relied on deleting active or filled openings. Since the behavior adheres to the data validation guidelines established in Greenhouse Recruiting, Greenhouse does not consider these issues a breaking change.

In the v2 version, response messages will include both IDs that were successfully deleted and any IDs that could not be deleted. Failed deletions can occur for a number of reasons, including the following examples: - The provided ID does not exist - The provided ID leads to an opening tied to an application or offer - The opening is currently open for applications

If the organization has deactivated the ability to destroy openings or if the On-Behalf-Of User does not have the ability to edit the given job, a 403 error will be returned.

The v1 endpoint has been deactivated as of 11/21/2022. Customers or partners should begin using the v2 endpoint.

API keys that were granted access to the v1 endpoint will automatically have access to the v2 endpoint.

The above returns a JSON response, structured like this

{
    "success": true
    "deleted_ids": [123, 456],
    "failed_ids": [789]
}

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,
    "custom_fields": [ { "id": 123, "value": "some value" } ]
}

HTTP Request

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

URL Parameters

Parameter Description
job_id The ID of the job on which to add new openings.
id The 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

Parameter Required Type Description
opening_id no string This 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.
status no string Accepts either "open" or "closed". This can be used to close an open opening with the word "closed" or to open a closed opening with the word "open". Official job approvals will be reset when opening a closed opening only if the Permission Policy named "Reopening a job with approval should require reapproval" is toggled on. If the last opening is closed, it will close the hiring plan.
close_reason_id no integer When closing, you may provide a close_reason_id. Providing a close_reason_id without closing the opening will return an error.
custom_fields no array Array of custom field objects containing updated values for custom fields on the opening. See the "Custom Field Object Parameters" section below for more details. Note: updating a custom field may reset official job approvals if this option is selected in the custom field settings page.

Note: If the job is closed at the same time the opening_id is changed, approvals will be ignored in favor of closing the opening.

Custom Field Object Parameters

The custom field parameter structure is different in the PATCH method than in GET methods and responses. Certain types of custom fields require different elements to be included. See below for the description of each item in a custom field element and what is required depending on the type.

Parameter Required for Description
id all The custom field ID for this particular custom field. One of this or name_key is required.
name_key all The name key for this custom field. This can be found in Greenhouse while editing custom options as Immutable Field Key. One of this or id is required.
value all 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's name exactly. See the Custom Field Object for more details.
min_value number_range, currency range The minimum value for a range. Must be less than max_value.
max_value number_range, currency_range The maximum value for a range. Must be greater than min_value
unit currency This 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_value n/a When 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. Required custom fields cannot be deleted and attempting to delete them will cause the request to fail.

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",
          "custom_fields": [ { "id": 123, "value": "some value" } ]
      },
      {"opening_id": null}
    ]
}

HTTP Request

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

URL Parameters

Parameter Description
job_id The ID of the job on which to add new openings.

JSON Body Parameters

Parameter Required Type Description
openings yes Array This an array of hashes, which can contain an opening ID and custom fields.
openings.opening_id yes Array This 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.
openings.custom_fields[] No Array Array of custom field objects containing new custom field values. Passing an empty array does nothing. If you have any required custom fields configured for openings, they must be supplied for each new opening, or the request will fail. See the "Custom Field Object Parameters" section below for more details.

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.

Custom Field Object Parameters

The custom field parameter structure is different in the POST method than in GET methods and responses. Certain types of custom fields require different elements to be included. See below for the description of each item in a custom field element and what is required depending on the type.

Parameter Required for Description
id all The custom field ID for this particular custom field. One of this or name_key is required.
name_key all The name key for this custom field. This can be found in Greenhouse while editing custom options as Immutable Field Key. One of this or id is required.
value all 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's name exactly. See the Custom Field Object for more details.
min_value number_range, currency range The minimum value for a range. Must be less than max_value.
max_value number_range, currency_range The maximum value for a range. Must be greater than min_value
unit currency This 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.

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": "Software Engineer",
  "location": {
    "id": 123456,
    "name": "New York, NY",
    "office_id": null,
    "job_post_custom_location_id": 303145,
    "job_post_location_type": {
      "id": 1,
      "name": "Free Text"
    }
  },
  "internal": true,
  "external": false,
  "active": true,
  "live": true,
  "first_published_at": "2023-04-03T18:06:18Z",
  "job_id": 1234,
  "content": "<p>We’re looking for the next big innovator.</p>",
  "internal_content": "<p>Apply today!</p>",
  "updated_at": "2024-11-21T15:39:24Z",
  "created_at": "2023-04-01T17:56:19Z",
  "demographic_question_set_id": 999,
  "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 worked for our organization before?",
      "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": "Have you applied to this job before?",
      "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

Attribute Description
id Job post ID
active If false, this job post has been deleted.
live If true, this job post status is set to live.
first_published_at Timestamp when this job post was first set to live.
internal If true, this job post has been posted (or is to be posted) on an internal job board.
external If true, this job post has been posted (or is to be posted) on an external job board.
job_id The ID of the job that this job post is for. Indicates a prospect post if null.
content The text of the job post as posted to the external job board.
internal_content The text of the job post if posted to the internal job board, if different than the external job board.
demographic_question_set_id The demographic question set associated with this job post
questions An array of questions associated with this job post.
questions.name When 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": "Software Engineer",
    "location": {
      "id": 123456,
      "name": "New York, NY",
      "office_id": null,
      "job_post_custom_location_id": 303145,
      "job_post_location_type": {
        "id": 1,
        "name": "Free Text"
      }
    },
    "internal": true,
    "external": false,
    "active": true,
    "live": true,
    "first_published_at": "2023-04-03T18:06:18Z",
    "job_id": 1234,
    "content": "<p>We’re looking for the next big innovator.</p>",
    "internal_content": "<p>Apply today!</p>",
    "updated_at": "2024-11-21T15:39:24Z",
    "created_at": "2023-04-01T17:56:19Z",
    "demographic_question_set_id": 999,
    "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 worked for our organization before?",
        "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": "Have you applied to this job before?",
        "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

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
*page A cursor for use in pagination. Returns the n-th chunk of per_page objects.
*skip_count If true, the performance of retrieving job posts will improve. This will remove last from the link response header.
created_before Return only job posts that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_after Return only job posts that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_before Return only job posts that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_after Return only job posts that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.
live If true, return only live job posts.
active If true, only return active job posts. If false, only return deleted job posts. When omitted, return both active and deleted job posts.
full_content If true, returns the board introduction, description, pay transparency ranges, and board conclusion as one content or internal_content element. When omitted, only returns the post's editable description.
internal If true, only return internal job posts. If false, only return external job posts. When omitted, return both internal and external 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": "Software Engineer",
    "location": {
      "id": 123456,
      "name": "New York, NY",
      "office_id": null,
      "job_post_custom_location_id": 303145,
      "job_post_location_type": {
        "id": 1,
        "name": "Free Text"
      }
    },
    "internal": true,
    "external": false,
    "active": true,
    "live": true,
    "first_published_at": "2023-04-03T18:06:18Z",
    "job_id": 1234,
    "content": "<p>We’re looking for the next big innovator.</p>",
    "internal_content": "<p>Apply today!</p>",
    "updated_at": "2024-11-21T15:39:24Z",
    "created_at": "2023-04-01T17:56:19Z",
    "demographic_question_set_id": 999,
    "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 worked for our organization before?",
            "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": "Have you applied to this job before?",
            "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}

Querystring parameters

Parameter Description
full_content If true, returns the board introduction, description, pay transparency ranges, and board conclusion as one content or internal_content element. When omitted, only returns the post's editable description.


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": "Software Engineer",
    "location": {
      "id": 123456,
      "name": "New York, NY",
      "office_id": null,
      "job_post_custom_location_id": 303145,
      "job_post_location_type": {
        "id": 1,
        "name": "Free Text"
      }
    },
    "internal": true,
    "external": false,
    "active": true,
    "live": true,
    "first_published_at": "2023-04-03T18:06:18Z",
    "job_id": 1234,
    "content": "<p>We’re looking for the next big innovator.</p>",
    "internal_content": "<p>Apply today!</p>",
    "updated_at": "2024-11-21T15:39:24Z",
    "created_at": "2023-04-01T17:56:19Z",
    "demographic_question_set_id": 999,
    "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 worked for our organization before?",
        "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": "Have you applied to this job before?",
        "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,
    "demographic_question_set_id": 999,
    "live": true,
    "first_published_at": "2023-04-03T18:06:18Z",
    "title": "Test job two",
    "location": {
      "id": 123457,
      "name": "Material Plane",
      "office_id": null,
      "job_post_custom_location_id": 303145,
      "job_post_location_type": {
        "id": 1,
        "name": "Free Text"
      }
    },
    "internal": false,
    "external": true,
    "job_id": 146218,
    "content": "job post content two",
    "updated_at": "2024-11-21T15:39:24Z",
    "created_at": "2023-04-01T17:56:19Z",
    "internal_content": "",
    "created_at": "2023-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
      }
    ]
  }
]

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

Parameter Description
id The ID of the job whose job posts you want to retrieve

Querystring parameters

Parameter Description
active If true, only return active job posts. If false, only return deleted job posts. When omitted, return both active and deleted job posts.
full_content If true, returns the board introduction, description, pay transparency ranges, and board conclusion as one content or internal_content element. When omitted, only returns the post's editable description.


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": "Software Engineer",
    "location": {
      "id": 123456,
      "name": "New York, NY",
      "office_id": null,
      "job_post_custom_location_id": 303145,
      "job_post_location_type": {
        "id": 1,
        "name": "Free Text"
      }
    },
    "internal": true,
    "external": false,
    "active": true,
    "live": true,
    "first_published_at": "2023-04-03T18:06:18Z",
    "job_id": 1234,
    "content": "<p>We’re looking for the next big innovator.</p>",
    "internal_content": "<p>Apply today!</p>",
    "updated_at": "2024-11-21T15:39:24Z",
    "created_at": "2023-04-01T17:56:19Z",
    "demographic_question_set_id": 999,
    "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 worked for our organization before?",
        "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": "Have you applied to this job before?",
        "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

Parameter Description
id The ID of the job whose job post you want to retrieve

Querystring parameters

Parameter Description
content If present, will return the text of the job post as posted to the external job board.
questions If present, will return an array of questions associated with this job post.
full_content If true, returns the board introduction, description, pay transparency ranges, and board conclusion as one content or internal_content element. When omitted, only return the post's editable description.


See noteworthy response attributes.

GET: Retrieve Custom Locations for Job Post

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

The above command returns JSON structured like this:

[
     {
         "id": 1234,
         "value": "Boston",
         "active": true,
         "greenhouse_job_board_id": 111,
         "created_at": "2019-05-15T15:19:53.617Z",
         "updated_at": "2019-05-15T15:19:53.617Z"
     },
     {
         "id": 2321,
         "value": "New York",
         "active": true,
         "greenhouse_job_board_id": 111,
         "created_at": "2019-05-15T15:53:35.586Z",
         "updated_at": "2019-05-15T15:53:35.586Z"
     },
     {
         "id": 4215,
         "value": "San Francisco",
         "active": true,
         "greenhouse_job_board_id": 111,
         "created_at": "2019-05-15T15:19:53.617Z",
         "updated_at": "2019-05-15T15:19:53.617Z"
     }
 ]

List all the custom location options available for a given job post ID

HTTP Request

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

URL parameters

Parameter Description
id The ID of the job post whose custom location options you want to retrieve

PATCH: Update Job Post

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

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

{
    "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/v2/job_posts/{id}

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
title No string The new title for this job post.
location No string The new location for this job post. This is just a plain text string.
location.office_id No integer The new location for this job post. This will be set by an office ID. Only acceptable if the job board location configuration is limited to offices.
location.custom_location_id No integer The new location for this job post. This will be set by a custom location ID. Only acceptable if the job board location configuration is limited to a custom list.
content No string The 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.

The V1 version of this endpoint was deprecated on 4/12/2020. To more correctly reflect job post permissions in Greenhouse Recruiting, updating the status of a job post was extracted into its own endpoint. We considered changing access permission to a job post a breaking change, so this V2 endpoint was created. Usage of this endpoint is the same as the V1 endpoint except it does not support updating status. To update status, use the Update Job Post Status endpoint below. The access permission in that endpoint is the same as the previous access permission in the V1 endpoint.

PATCH: Update Job Post Status

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

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

{
    "status": "live", (or "offline")
}

The above returns a JSON response on success:

{
    "success": true
}

Update the status of a job post to "live" or "offline."

HTTP Request

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

Headers

Header Description
On-Behalf-Of ID of the user issuing this request. Required for auditing purposes.

JSON Body Parameters

Parameter Required Type Description
status Yes string One of 'live' or 'offline'

The ability to update a job post's status is on a different permission than the other properties of a job post. To reflect this in Harvest, status was separated into its own endpoint in V2. Updating status on the V1 endpoint is deprecated.

Job Stages

An organization's job stages.

The job stage object

{
  "id": 72200,
  "name": "Face to Face",
  "created_at": "2016-10-22T05:31:37.263Z",
  "updated_at": "2016-10-22T05:31:37.263Z",
  "active": true,
  "job_id": 98765,
  "priority": 0,
  "interviews": [
    {
      "id": 6001,
      "name": "Cultural Fit Interview",
      "schedulable": true,
      "estimated_minutes": 30,
      "default_interviewer_users": [
        {
          "id": 821,
          "first_name": "Robert",
          "last_name": "Robertson",
          "name": "Robert Robertson",
          "employee_id": "100377"
        }
      ],
      "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",
      "schedulable": true,
      "estimated_minutes": 60,
      "default_interviewer_users": [
        {
          "id": 4080,
          "first_name": "Kate",
          "last_name": "Austen",
          "name": "Kate Austen",
          "employee_id": "12345"
        }
      ],
      "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

Attribute Description
id The job stage's unique identifier
name The name for this job stage
active One of true or false:
true - The job stage is active
false - The job stage was deleted
job_id The job that this stage belongs to
priority Numeric field used for ordering, with the lowest values ordered first. For example, priority 0 indicates the first stage on a job
interviews An array of interview steps associated with this job stage.
Each Step contains:
id - The step's unique identifier
name - The name of this interview step
schedulable - True / False value for whether this step can be scheduled
interview_kit - Details about the interview, including unique ID, interview prep content, and custom interview questions

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,
    "priority": 0,
    "interviews": [
      {
        "id": 7890,
        "name": "Cultural Fit Interview",
        "schedulable": true,
        "estimated_minutes": 30,
        "default_interviewer_users": [
          {
            "id": 821,
            "first_name": "Robert",
            "last_name": "Robertson",
            "name": "Robert Robertson",
            "employee_id": "100377"
          }
        ],
        "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,
    "priority": 1,
    "interviews": [
      {
        "id": 7345,
        "name": "Executive Interview",
        "schedulable": true,
        "estimated_minutes": 60,
        "default_interviewer_users": [
          {
            "id": 4080,
            "first_name": "Kate",
            "last_name": "Austen",
            "name": "Kate Austen",
            "employee_id": "12345"
          }
        ],
        "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

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
*page A cursor for use in pagination. Returns the n-th chunk of per_page objects.
*skip_count If true, the performance of retrieving job stages will improve. This will remove last from the link response header.
created_before Return only job stages that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_after Return only job stages that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_before Return only job stages that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_after Return 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,
    "priority": 0,
    "interviews": [
      {
        "id": 6001,
        "name": "Cultural Fit Interview",
        "schedulable": true,
        "estimated_minutes": 30,
        "default_interviewer_users": [
          {
            "id": 821,
            "first_name": "Robert",
            "last_name": "Robertson",
            "name": "Robert Robertson",
            "employee_id": "100377"
          }
        ],
        "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",
        "schedulable": true,
        "created_at": "2015-11-22T05:31:37.263Z",
        "updated_at": "2015-11-22T05:31:37.263Z",
        "job_id": 146219,
        "estimated_minutes": 60,
        "default_interviewer_users": [
          {
            "id": 4080,
            "first_name": "Kate",
            "last_name": "Austen",
            "name": "Kate Austen",
            "employee_id": "12345"
          }
        ],
        "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,
    "priority": 1,
    "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,
    "priority": 2,
    "interviews": [
      {
        "id": 8004,
        "name": "Application Review",
        "schedulable": false,
        "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

Parameter Description
id The ID of the job whose job stages you want to retrieve.

Querystring parameters

Parameter Description
created_before Return only job stages that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_after Return only job stages that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_before Return only job stages that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_after Return 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,
  "priority": 1,
  "interviews": [
    {
      "id": 7890,
      "name": "Cultural Fit Interview",
      "schedulable": true,
      "estimated_minutes": 30,
      "default_interviewer_users": [
        {
          "id": 821,
          "first_name": "Robert",
          "last_name": "Robertson",
          "name": "Robert Robertson",
          "employee_id": "100377"
        }
      ],
      "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

Parameter Description
id The 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",
  "updated_at": "2013-12-12T14:42:58Z",
  "is_template": false,
  "copied_from_id": 2345,
  "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

Attribute Description
id The job's unique identifier
requisition_id An arbitrary ID provided by an external source; does not map to another entity within Greenhouse.
status One of open, closed, draft.
confidential One of true, false. If the job is confidential or not.
departments An array containing the department which this job belongs to.
offices An array containing the offices this job is associated with.
hiring_team Lists 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_fields Contains any custom job fields which have been defined by your organization.
keyed_custom_fields This 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.
openings Lists the openings associated with this job.
openings[].opening_id Custom identifier set by an organization. Can be null.
openings[].status One of: ["open", "closed"]
openings[].opened_at Timestamp when the opening was opened.
openings[].closed_at Timestamp when the opening was closed. An opening is closed when it is filled or removed.
openings[].application_id If 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_reason If 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.
is_template Is this job designated as a template used to create other jobs. This may be true, false, or null. Null is an indication this job was created before template job feature.
copied_from_id If this job was copied from another job, this field contains the id of the source job.

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",
    "updated_at": "2013-12-12T14:42:58Z",
    "is_template": false,
    "copied_from_id": 2345,
    "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

Parameter Description
*per_page Return up to this number of objects per response. Must be an integer between 1 and 500. Defaults to 100.
*page A cursor for use in pagination. Returns the n-th chunk of per_page objects.
*skip_count If true, the performance of retrieving jobs will improve. This will remove last from the link response header.
created_before Return only jobs that were created before this timestamp. Timestamp must be in in ISO-8601 format.
created_after Return only jobs that were created at or after this timestamp. Timestamp must be in in ISO-8601 format.
updated_before Return only jobs that were updated before this timestamp. Timestamp must be in in ISO-8601 format.
updated_after Return only jobs that were updated at or after this timestamp. Timestamp must be in in ISO-8601 format.
requisition_id If included, will return only the jobs that match the given requisition_id
opening_id If included, will return only the jobs that contain at least one opening with the given opening_id.
status One of 'open', 'closed', or 'draft'. If included, will only return jobs with that status.
department_id If included, will return only the jobs in this specific department.
external_department_id This may be used instead of department_id and represents the ID of the department in an external system.
office_id If included, will return only the jobs in this specific office.
external_office_id This may be used instead of office_id and represents the ID of the office in an external system.
custom_field_option_id The 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",
  "updated_at": "2013-12-12T14:42:58Z",
  "is_template": false,
  "copied_from_id": 2345,
  "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

Parameter Description
id The 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",
  "updated_at": "2013-12-12T14:42:58Z",
  "is_template": false,
  "copied_from_id": 2345,
  "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"