Jump to section:
Greenhouse is the leading hiring software for growing companies. Greenhouse Recruiting drives engaging candidate interactions at every touchpoint, eliminates administrative burden and keeps everyone on the hiring team engaged.
This guide is to teach you how to integrate your Greenhouse account with your Vetty account. This will automatically invite the candidate to Vetty when you move the candidate to your "Background Check" Stage in Greenhouse.
Before proceeding with the Greenhouse and Vetty integration, the following steps need to be followed:
- The organization must have a Greenhouse account and must be registered as a client in Vetty.
- The user configuring the integration must have an account with Site Admin and Developer permissions in Greenhouse.
To create a user account with developer permissions in Greenhouse:
In order to proceed with a Greenhouse integration with Vetty, your user account in Greenhouse with developer permissions must include both:
- Can manage ALL organization’s API Credentials
- Can manage and configure web hooks
If you are a Site Admin without these permissions, someone from your team who is also a site admin can grant them for you.
Now, let's start integrating the two systems
Adding a web hook
Web hooks act as a bridge for the Greenhouse and Vetty integration. To configure the webhooks to the greenhouse account, you will first need the Endpoint URL as provided by the Vetty team.
Note: If you do not have this yet, you can get this easily by emailing your account manager, or by emailing firstname.lastname@example.org.
Once in possession of the URL, follow these steps in Greenhouse:
Configure > Dev Center > Web Hooks > Web Hooks
Create a New Web Hook
Within the Web Hooks Section is where you will stage details, that tells the Vetty platform when to deploy a check. Please follow the below steps:
- Name this Webhook - Generally, most simply choose “Vetty Web Hook” or "Vetty"
- “When” - Please select "Candidate has changed stage"
- Endpoint URL - Please utilize the Endpoint URL given to you by the Vetty account manager. It will be https://api.vetty.co/ats/webhook_processor/company_name/[companyname]
- Create an appropriate secret key and provide that webhook secret key to your Vetty account manager. This can be whatever you like. It is case sensitive, so be sure to send the exact match to your account manager
- Fill in an appropriate email address to for error handling
- Leave the selector for Disabled to be No
- Click on Create Web Hook button to complete set up the web hook.
Create a Harvest API key
It is time to set up a New Harvest API key. The user will have access to a page that lists all the API credentials (if any). Please follow the below instructions:
Configure > Dev Center > API Credentials > Create New API Key
- Type: Select Harvest
- Partner: Vetty
- Description: the general recommendation is to put Vetty
- Manage Permissions
COPY Your API Key and place in an email to your Account manager. This is needed for the Integration
Managing API Permissions
In the same API Credentials tab is where you will now set up, enable, and manage permissions.
Select the checkboxes as follows:
- DELETE: Delete Application
- GET: Retrieve Application
- GET: List Applications
- PATCH: Update Application
- POST: Advance Application
- POST: Move Application
- POST: Reject Application
- POST: Moves Application to Job
- POST: Unreject Application
- GET: Retrieve Candidate
- GET: List Candidates
- PATCH: Edit Candidate
- POST: Add Note
- GET: Retrieve User
- GET: List Users
- GET: List Application's Offers
- GET: Retrieve Application's Current Offer
- GET: Retrieve Offer
- GET: List Offers
- Activity Feed - Select All
- GET: Retrieve Activity Feed
- GET: Retrieve Job
- GET: List Jobs
- Job Posts
- GET: List Job Posts
- GET: Retrieve Job Post for Job
- Job Stages - Select All
- GET: Retrieve Job Stage
- GET: List Job Stages
- GET: List Job Stages for Job
- GET: Retrieve Office
- GET: List Offices
- Custom Fields: Select All
- GET: Get Custom Fields
- POST: Create Custom Field
- DELETE: Delete Custom Field
- PATCH: Update Custom Field
- Custom Field Options
- GET: Custom field options
- DELETE: Remove custom field options
- PATCH: Update custom field options
Create Custom Options for Vetty
Now, after the permissions for API key is configured, you have to create 3 custom Candidate options which will be used by Vetty to populate the background check details in your greenhouse portal.
Start by clicking Configure > Custom Options > Candidates > Add Field
Now, create three custom fields with these exact names: Background , Background Status and Report.
Background and Background Status are the "Field Type" Short textbox and Report is the "Field Type" of URL. Please mark all of the custom fields as Private.
This ensures that only your users with Private fields permissioned will be able to check the status of background checks
Provide Information to Vetty to complete integration!
Now that the newly added harvest API key has to be configured on the Greenhouse system, it’s time to provide just a few details to your Vetty account manager, or to support@vetty. They will need:
- Copy of API key
- The Secret Key
- The name of the user in Greenhouse that you would like to manage this integration
Deploy Checks and Review Background Check Statuses
New checks that are moved to the background check stage will trigger an order to the Vetty system. The background check details will be updated on the Greenhouse platform automatically in the “Private Tab”.
To review the background check report, simply click on the link, sign in to your Vetty account, and review.
A Few more Options to Customize the Integration
If you have multiple Background Check packages that you want to run on many different roles, you will need to set up another Custom Option in Greenhouse.
- If you have many jobs and many job titles with many package options, the best option is to select the check package on the Greenhouse side.
- If you have few job titles & openings that need a package other than the default, the best option is to map the Job Opening name to the package in Vetty.
If You need to Select a Check Package from the Greenhouse side
Navigate to Configure > Custom Options > Jobs > Add Field
The field name must be exactly “Background Package”
- Field Type: Single Select
- Options: the Options listed need to match the exact names of the background check packages in your Vetty account. You can email your Account Manager for this information or find it in the Packages Tab within Vetty
- Mark Required
Now, in order to map each job to the correct package, you will select which background package you need when creating the job. Don't forget to edit this field for your current job openings!
If you would like to map the job name to the Packages in Vetty.
- If you decided not to go the custom Job option route, please provide the name of the job and package you want associated to that job role to your Vetty Account Manager. If you do not know who this is, please email email@example.com
- For example, an "Outside Sales Representative" may get the “Criminal + MVR” package. The package name can be found on the Vetty Dashboard by click “Packages”. In any where you have not specified which background check package, a default package in your Vetty client profile will be assigned.
Once this information has been provided to the Vetty team, your account manager will confirm receipt and will proceed with linking the job openings with the background package.