API approach to candidate export integration

Permissions: Basic and above, who can manage all organization's API Credentials

Product tier: Available to all subscription tiers

Some organizations aren’t able to build the candidate export integration with the candidate-hired webhook because the HRIS or integration partner does not have a listener service that can accept webhooks. To get around this issue, you can pull data from the API instead of leveraging Greenhouse Recruiting webhooks.

Tip: If your organization needs to utilize this approach, we recommend pulling a list of offers that were accepted during a specific period of time, then using the application ID, candidate ID, and job ID returned in that API response to make subsequent API requests for any additional information that is required by the relevant HRIS.

API request steps

Step 1

Poll GET List Offers using the status, resolved_after, and starts_before/starts_after parameters

  • This method will return the application_id, candidate_id, and job_id that you need to retrieve the application, candidate, and job data
  • Adding Status=accepted ensures that all returned candidates have been hired
  • Including Resolved_after=[date/time] ensures that the integration is only pulling offers that were marked as accepted since the last time the integration polled Greenhouse
  • Adding Starts_before=[date/time] and starts_after=[date/time] will pull offers for candidates expected to start within the designated time frame

Example Request:

curl -X GET \  'https://harvest.greenhouse.io/v1/offers?status=accepted&resolved_after=2019-04-01T00:00:00.000Z' \

  -H 'Authorization: Basic ***********************************'

Example Response

(application_id, job_id, and candidate_id included in the response body):

[
   {
       "id": 1713400,
       "version": 1,
        "application_id": 116713091,
       "created_at": "2019-07-11T12:57:55.551Z",
       "updated_at": "2019-07-15T20:09:59.530Z",
       "sent_at": null,
       "resolved_at": "2019-07-15T20:09:59.529Z",
       "starts_at": "2019-08-15",
       "status": "accepted",
        "job_id": 1026114,
       "candidate_id": 106907233,
       "opening": null,
       "custom_fields": {
           "employment_type": "Full-time",
           "legal_name": “Cindy Bananas”,
           "compensation_plan": "Compensation Plan B",
           "salary": {
               "value": 100000,
               "unit": "USD"
           },
           "bonus": null,
           "options": "updated offer",
           "benefits": null,
           "visa_cost": "n/a",
           "notes": "notes notes notes",
           "offer_date": "2019-03-27",
           "hiring_manager": {
               "name": "Nastia Liukin",
               "email": "ghtest+nliukin@gmail.com",
               "user_id": 1019645
           },
           "return_date": "2019-09-26",
           "boolean_test": "Yes"
       }
   }
]

Step 2

Using the application_id, job_id, and candidate_id returned in the response body from step 1, execute the below requests to pull the corresponding application, job, and candidate data that would have been included in the Candidate Hired webhook:

Step 3

Use GET Retrieve Candidate to pull candidate data and candidate field values.

The Candidate object will include the candidate’s first and last name, contact details, and education info.

Example Request: 

curl -X GET \
  https://harvest.greenhouse.io/v1/candidates/106907233 \
  -H 'Authorization: Basic ***********************************'

Step 4

Use GET Retrieve Application to pull application data and application field values.

The Application object will include the specific Opening ID that the candidate has been hired onto (this may correlate with the Requisition/Position ID), the candidate source, and which Greenhouse user that will receive credit for the referral.

Example Request: 

curl -X GET \
  https://harvest.greenhouse.io/v1/applications/116713091 \
  -H 'Authorization: Basic ***********************************'

Step 5

Use GET Retrieve Job to pull job data and job field values.

The Job object will include the Requisition ID and Opening ID which typically identify the Requisition and/or Position in the HRIS.  

Example Request: 

curl -X GET \
  https://harvest.greenhouse.io/v1/jobs/1026114 \
 -H 'Authorization: Basic ***********************************'