Greenhouse Integration

Jump to section: 
Before You Begin
Add and Create a Web Hook
Create a Harvest API Key
Managing API Permissions
Create Custom Candidate Fields
Send the Details to Vetty
Deploy Checks and Review Reports
More Options to Customize Your Integration

Greenhouse is one of the most popular recruiting platforms for growing teams and for good reason. It keeps your hiring organized, your candidates engaged, and your recruiters sane.

When you integrate Greenhouse with Vetty, you can kick your background screening process into autopilot. Move a candidate into your “Background Check” stage, and Vetty takes it from there. Easy. Here’s how to make it happen.

Before You Begin

A little prep goes a long way. Make sure you have the following before getting started:

• A Greenhouse account
• A Vetty account
• A Greenhouse user account with Site Admin and Developer permissions

Your Greenhouse account must include both of these permissions:

• Can manage ALL organization’s API Credentials
• Can manage and configure webhooks

If you’re a Site Admin but don’t see these permissions, another Site Admin on your team can help you out.

Now, let's start integrating the two systems.

Add and Create a Web Hook

Think of webhooks as little messengers that tell Vetty when it’s time to start a background check. To set one up, you’ll need the endpoint URL from the Vetty team.

Don’t have it yet? Just email your Customer Success Manager (CSM) or drop us a note at support@vetty.co.

Once you have the URL, head over to your Greenhouse account and follow these next steps:

• Head to Configure   > Dev Center > Web Hooks
• Click Create a New Web Hook
• Fill out the details:
  • Name: Vetty Web Hook (or just Vetty if you’re feeling minimal).
  • When: Select Candidate has changed stage.
  • Endpoint URL: Use the URL provided by your Vetty CSM — it’ll look something like this: https://api.vetty.co/ats/webhook_processor/company_name/[companyname]
  • Secret Key: Create one (anything you like!) and share it exactly as is with your Vetty CSM.
  • Error handling email: Add your contact email.
  • Disabled: Set to No
  • Hit Create Web Hook, and you’re done!

Create a Harvest API key

This key gives Vetty access to the right data in Greenhouse so we can work our background check magic.

Here’s how to make one:

1. In your Greenhouse account, go to Configure > Dev Center > API Credentials > Create New API Key

2. Fill in the details:

   • Type: Harvest

   • Partner: Vetty

   • Description: “Vetty” (Best to keep it simple!)

3. Copy your API Key and send it to your Vetty CSM, we’ll need this to finalize your integration.

Managing API Permissions

Next, let’s set up the right permissions so Vetty can communicate with Greenhouse correctly.

In the same API Credentials tab, check the following boxes:

 

• Applications
  • 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
• Candidates
  • GET: Retrieve Candidate
  • GET: List Candidates 
  • PATCH: Edit Candidate
  • POST: Add Note
• Users
  • GET: Retrieve User
  • GET: List Users
• Offers
  • GET: List Application's Offers
  • GET: Retrieve the Application's Current Offer
  • GET: Retrieve Offer
  • GET: List Offers
• Activity Feed - Select All
  • GET: Retrieve Activity Feed
• Jobs
  • 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
• Offices
  • 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

Click Save when finished.

Create Custom Candidate Fields

These fields let Vetty send background check updates directly into Greenhouse, so you can see candidate status without switching tabs. 

Go to Configure > Custom Options > Candidates > Add Field and create three fields exactly as follows:

Background

• Type: Short Textbox
• Mark Private
• Save, and follow the above steps to create a new field

Background Status

• Type: Short Textbox
• Mark Private
• Save, and follow the above steps to create a new field

Report.

• Type: URL
• Mark Private
• Save

Only users with permission to view private fields will see these details.

Send the Details to Vetty

Almost there! Email your Vetty CSM (or support@vetty.co) with the following:

• Your API Key.

• Your Web Hook Secret Key.

• The name of the Greenhouse user managing the integration.

Once we have that, we’ll connect everything on our end and confirm when your integration is live.

Deploy Checks and Review Reports

Now for the fun part. Every time you move a candidate into your Background Check stage, Vetty automatically kicks off the background check process.

You’ll see real-time updates in Greenhouse under the Private Tab.

When your report is ready, click the link to view it and you’ll be prompted to sign in to your Vetty account.

More Options to Customize Your Integration

If you have multiple background check packages that you want to run on a variety of roles, you can customize how different roles trigger different Vetty packages.

Option 1: Choose Packages in Greenhouse

If you have several background check packages, create a new custom field:

• Go to Configure > Custom Options > Jobs > Add Field.

• Name it Background Package.

• Field Type: Single Select.

• Options: List the package names exactly as they appear in your Vetty account (your CSM can help if you’re not sure).

• Mark as Required, then click Save.

When you create or edit a job, choose the background package that fits.

Option 2: Let Vetty Map It for You

Prefer less setup? Just send your CSM a list of job titles and which package should go with each one.

Example: “Outside Sales Representative” → “Criminal + MVR” package

If no mapping is specified, Vetty will use your default package...easy peasy.

Once we’ve got the list, we’ll handle the rest and confirm it’s all linked up.

And that's it! 

Your Greenhouse and Vetty integration is now live and ready to roll. From here on out, background checks will automatically flow whenever you move a candidate into the right stage. Go ahead, take that victory sip of coffee.