Referrals ⚡ by Roots is a Slack app that streamlines the candidate referral experience for your team and allows recruiters/admins to curate referrals at scale with automated job boosts in various Slack channels — highlighting the newest jobs, oldest jobs, jobs with the fewest applicants, specific jobs, and so on.

Once configured, the app pulls all open jobs from Greenhouse Recruiting into Slack, where users can search through them and add referrals at will. Any referrals submitted through Referrals ⚡ by Roots immediately create a new candidate/opportunity in Greenhouse Recruiting with the proper information and referrer attributed.


Configure user setup permissions in Greenhouse Recruiting

To enable the Referrals ⚡ by Roots integration, you need the developer permission Can manage ALL organization’s API Credentials.

Contact a Greenhouse Recruiting 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 User-Specific Permissions panel on your user page and expand the Developer Permissions dropdown menu. 

Select Can manage ALL organization’s API Credentials so 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 Harvest API key in Greenhouse Recruiting

To create a Harvest API key for the integration, click the Configure icon in the upper-right corner, and navigate to Dev Center on the left 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 Referrals ⚡ by Roots.


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

  • API Type: Harvest
  • Partner: Referrals by Roots
  • Description: Referrals by Roots Harvest API Key

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


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 Referrals ⚡ by Roots 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:

  • Applications:
    • GET: Retrieve Application
    • GET: List Applications
    • POST: Add Attachment to Application
  • Candidates:
    • GET: Retrieve Candidate
    • GET: List Candidates
    • PATCH: Edit Candidate
    • POST: Add Candidate
    • POST: Add Attachment 
    • POST: Add Application
  • Custom Fields:
    • GET: Get custom fields
  • Job Posts:
    • GET: List Job Posts
    • GET: Retrieve Job Post for Job
    • GET: List Job Posts for Job
  • Job Stages:
    • GET: Retrieve Job Stage
    • GET: List Job Stages
    • GET: List Job Stages for Job
  • Jobs:
    • GET: Retrieve Job
    • GET: List Jobs
  • Sources:
    • GET: List Sources
  • Users:
    • GET: Retrieve User
    • GET: List Users

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 Referrals ⚡ by Roots integration is created and configured. 

Return to Referrals ⚡ by Roots in Slack and add the Harvest API key you just created. Some tests will be run to ensure the right permissions were added to the key. Follow the directions that appear on screen. 

Use the Referrals ⚡ by Roots integration

Once your integration is finalized, open jobs are synced from Greenhouse Recruiting into Referrals ⚡ by Roots within 15 minutes. Then, users can easily filter those jobs by department or location and add referrals accordingly.


Clicking any Add Referral button opens the referral submission form, where users can input information about the candidate they’d like to refer. If there are specific questions or fields that need to be filled out for a referral and you have a form set up in Greenhouse Recruiting where these questions/fields are listed, reach out to to have that form pulled into this sequence programmatically.


After a referral is submitted, the candidate/opportunity populates in Greenhouse Recruiting with the proper user/referrer attributed.


As candidates are updated and moved through stages in Greenhouse Recruiting, Referrals ⚡ by Roots reflects those updates in Slack, so the user can keep track of their submissions without needing to ping admins/recruiters for updates.


To learn more about the Referrals ⚡ by Roots feature set, check out the demo video listed here.