How can we help you?


The ESS integration allows you to automatically take newly-hired candidates from Greenhouse and add them to ESS. To link your Greenhouse account, contact ESS Customer Success for an endpoint url and a secret key you'll need to get started. Once you have both of those items, complete the following steps to link your accounts!


In Greenhouse:

Part 1: Setting up admin access.  

1. Ask a Site Admin with Advanced permissions to log into Greenhouse

2. Have them select Configure > Users > Your Name

3. At the bottom of the page, select Can manage and configure web hooks

4. Save

5. Repeat for anyone else that should have access


Part 2: Creating the ESS Web Hook


1. Now that you have the correct permissions, log into your Greenhouse account

2. Select Configure > Dev Center > Web Hooks > Web Hooks

3. You'll land on a page called Create a New Web Hook


4. Name your Webhook — we suggest ESS Integration

5. Input the Endpoint URL and Secret Key provided to you by ESS Customer Success, then

make sure the webhook is executed (“When”) the “Candidate has changed stage”

6. Expand “Advanced Settings”, re-enter the “Secret Key” in the “Username” field

7. Select “No” for the ‘Disabled?” toggle

8. Press Create Web Hook


That's it! Your Greenhouse account and ESS account can now talk to each other. These settings dictate execution of the ESS web hook once the end user transitions the candidate into an appropriate application stage for a given job.


Part 3: Creating the Candidate Custom Fields

1. Select “Custom Options” in the Configure section.

2. Select “Candidates”.

3. Click “+ Add Field”.

4. Add “Background Check Status” in the “Field” name and select “Short Textbox” as “Type”

5. Click Save

6. Add “Background Check Result” in the “Field” name and select “URL” as “Type”

7. Click Save

8. Add “Background Check Completed Date” in the “Field” name and select “Short Textbox”

as “Type”

9. Click Save

This portion of the configuration allows ESS to provide Background Check status, a link to the Background Check report (when applicable), and the date the report is completed.


Part 4: Creating the Jobs Custom Fields

1. Add “Background Check Package” in the “Field” name and select “Single Select” as

“Type;” under “Options”, list all of your available packages (return after each package ID).

2. Mark as “Required” and click Save

3. Add “Background Check Location” in the “Field” name and select “Single Select” as

“Type”;” under “Options”, list all of your available locations (return after each package ID).

4. Mark as “Required” and click Save


This portion of the configuration allows the end user to select the applicable package and location necessary to complete the Background Check. It is necessary to select Package and Location for EACH job in Greenhouse.




 Viewing Integration Order (Click here for Image)


1) Once a background check is initiated through Greenhouse, a request to complete the

background check will be sent to the candidate’s email.

2) The Candidate will complete the required fields and sign off on the consent.

3) ESS receives the request then will send an update to Greenhouse that the order is in


4) Once the report is completed in the Deverus platform, a status update is sent to

Greenhouse with the results report

After using the integration, you may decide you want to share more information between Greenhouse and ESS. If you would like additional information transferred over, please reach out to ESS Customer Success with a list of items to add!