Emptor provides quick and reliable identity verification and background checks with its automated platform.

Greenhouse Recruiting’s integration with Emptor provides automated background checks screenings focused in Latin America. In this article, we will cover how to:

  • Configure User Setup Permissions in Greenhouse Recruiting
  • Create a Harvest API Key for the Greenhouse/Emptor Integration
  • Get access to the Emptor’s Background Check API and Onboarding
  • Setup the Webhook integration

Configure User Setup Permissions in Greenhouse Recruiting

In order to enable the Greenhouse/Emptor integration, you will need the developer permission “Can manage ALL organization’s API Credentials”.

Contact a Greenhouse user in your organization with Site Admin level permissions with the additional user-specific permission Can edit another user's advanced permissions to apply the API credential management permission to your account. Have the user with Site Admin level permissions edit your user account's permissions by navigating to the Configure icon   > Users > Your Name).

The user with Site Admin level permissions should navigate to the Permissions panel on your user page and expand the Developer Permissions dropdown menu. 

Select Can manage ALL organization’s API Credentials so that a check is in the checkbox. When finished, click Save.

Repeat as necessary for any other user that should have access to set up the integration.

Create a Harvest API Key for the Greenhouse/Emptor Integration

To create a Harvest API key for the integration, click on the Configure icon  in the upper right-hand corner. Navigate to Dev Center on the left-hand panel.

From the Dev Center page, click API Credential Management.



From the API Credential Management page, click Create New API Key to generate the API key for Emptor.



In the Create New Credential dialog box, make the following selections:

  • API Type: Harvest
  • Partner: Emptor
  • Description: Emptor Harvest API Key

When finished, click Manage Permissions to generate the Harvest API key and automatically assign it the appropriate permissions required by Emptor.



In the subsequent dialog box, click Copy to save your API key to your clipboard. Store the API key in a secure location to provide to Emptor in the next step. Click I have stored the API Key once you have copied and saved the key.


Note: You cannot access the full API key again after clicking I have stored the API Key. If you lose your API key and need to access it later, you must create a new API key, provide it to the integration partner, and then revoke access to the original key.



On the subsequent page, confirm the following permissions are assigned to your new API key:


Under Applications:

  • Retrieve Application
  • List Applications
  • Advance Application


Under Candidates:

  • Retrieve Candidate
  • List Candidates
  • Edit Candidate
  • Add Note


Under Tags:

  • List tags applied to candidate
  • List candidate tags
  • Add New Candidate Tags
  • Add a candidate tag


Under Users:

  • Retrieve User
  • and List Users


Under Job Stages:

  • Retrieve Job Stage
  • List Job Stages
  • List Job Stages for Job


Under Custom Fields:

  • Get custom fields
  • Create custom field
  • Delete custom field
  • Update custom field


Under Custom Field Options:

  • Get custom field options
  • Create custom field options
  • Remove custom field options
  • Update custom field options


When finished, click Save.

If any of the permissions above are not checked, place a check in the box next to the appropriate permission. Click Save when finished.

Your Harvest API key for the Greenhouse/Emptor integration is created and configured. Provide your Harvest API key to your Emptor onboarding team so they can set up the integration. For more information you can see our setup video in https://youtu.be/TFef9VeEhK4?t=101


Get access to the Emptor’s Background Check API and Onboarding


You will need access to Emptor's Background Check API.  If you are not already an Emptor customer, please visit our website at www.emptor.io to sign up, or contact our sales team for more information at info@emptor.io.


The Emptor onboarding team will start the onboarding process which will create all the necessary custom fields, and provide you with the webhook credentials to send the information from Greenhouse to Emptor’s Background Check API.


For certain tasks, Emptor's Greenhouse integration must act on behalf of a user account in your Greenhouse organization.  This is for your organization's logging and auditing purposes only in Greenhouse API, we will never use this account to login or directly access your organization's Greenhouse control panel in any way, and the password for this account should never be given to Emptor personnel.  We sometimes refer to this as a "bot account", because it will only be used by the automated system that connects Emptor's Background Check API to your Greenhouse organization.


Setup the Webhook integration


Once your Emptor Greenhouse Integration Onboarding has been fulfilled, you will be given Emptor's Greenhouse Web Hook URL and Secret Key, which will allow you to fully complete and enable your Emptor integration. To do this, click the Configure icon  in the top right corner.



Then, click the Dev Center link in the left column.


Next, click Web Hooks.



















On the Web Hooks page, click the top link in the main list, which is also labeled Web Hooks.

This will take you to the "Create A New Web Hook" page.  In this form, start by entering a descriptive name that your organization administrators will recognize, such as "Emptor Integration".

Next, in the "When" field, select "Candidate has changed stage".


In the "Endpoint URL" field, enter the Emptor Web Hook URL provided to you by the Emptor Customer Success team.


In the "Secret Key" field, enter the Emptor Web Hook Secret Key provided to you by the Emptor Customer Success team.



For the "Error recipient email" field, you may enter the Greenhouse error email address provided to you by Emptor's Customer Success team to automatically receive technical support from Emptor if an error occurs, without needing to contact us manually.  This can also point to an internal email address if preferred, but we do not recommend leaving it blank.


Below the "Error recipient email" field, click the "Advanced settings" link to show more fields.  Most of these can be ignored, but the field labeled "Additional HTTP Headers" is required for Emptor's Web Hook API.  Copy and paste the text provided for this field, exactly as it appears in the onboarding instructions from Emptor, starting with "x-api-key:".


Lastly, set the "Maximum Attempts" field to 5, make sure the "Disabled?" field is set to "No", and click the "Create Web Hook" button.


For more information on how to setup the webhook see this video https://youtu.be/TFef9VeEhK4?t=202



How to use the Emptor Integration with Greenhouse


Emptor's Greenhouse integration automates background checks in one country of your choice, which will be selected during the onboarding process.  A list of available countries and reports can be found on our website at https://emptor.io/our-product/


  1. Set the Document ID of the person in the custom field in the Details tab
  2. Once the candidate is moved to the “Background Check” stage, Emptor will start the background check process
  3. Emptor will populate custom fields with the background check status and results as that information becomes available.
  1. Emptor Country: Country code for Emptor Background Check requests
  2. Emptor Report Requests: List of Emptor Background Check reports to perform for this person
  3. Emptor Folder Status: Folder Status
  4. Emptor System Status: Status of this person's Emptor Background Check request.
  5. Emptor ID: The ID for this person's report records in Emptor's Background Check system.
  6. Emptor Report Details: Details of all Emptor Background Check reports successfully performed for this person.
  7. Emptor System Timestamp: Timestamp of last attempted operation on Emptor Background Check API. Used for debugging and technical support.
  8. Emptor System Message: Detailed system status message from last attempted operation on Emptor Background Check API. Used for debugging and technical support
  1. Emptor will advance the candidate to the next stage if the Emptor Folder Status is PASSED, indicating a successful background check.  Otherwise, the candidate will remain in the same stage.





For more information on how the integration works, see our video https://youtu.be/TFef9VeEhK4?t=267






Need help?


What happens if there is any error?


Errors will be displayed in the Emptor System Message custom field under the candidate's detail tab.



This integration uses the Emptor Background Check API, which is priced based on the API usage. Contact Emptor at https://emptor.io/contact/ for more information.

Please contact info@emptor.io for troubleshooting assistance regarding the integration.