Greenhouse Recruiting’s integration with Scholars allows users to connect their Greenhouse account to our application via the Harvest API. By allowing users to connect to their account, they are able to push multiple candidates’ information for different active jobs that they already have stored in their Greenhouse account. Our software retrieves all the user’s active jobs so that they are able to select and export all the candidates they want from our list of candidates to the Greenhouse platform. In this article, we will cover how to:
- Configure User Setup Permissions in Greenhouse Recruiting
- Retrieve Scholars’s Endpoint URL and Secret Key
- Enable Greenhouse/Scholars Integration
Explanation of Use
After integration is started, Harvest API is used to:
- Get list of jobs
- Export candidates from Scholars to Greenhouse
- Need endpoint, secret key-- both provided by Scholars
- Endpoint: a URL where webhook events can send requests
- Secret key: a randomly generated string, used to sign requests sent from Greenhouse to the Scholars webhook endpoint
Configure User Setup Permissions in Greenhouse Recruiting
In order to enable the Greenhouse/Scholars 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 menu > 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.
Get the Harvest API Key
Now that you have enabled the developer permissions on your Greenhouse account, you can get the Harvest API Key. Navigate to app.greenhouse.com/configure/dev_center, then click on “API Credential Management”.
Once at the API Credential Management page, click “Create New API Key”. You’ll be prompted to add a description and select the type for the new API key. Type in a description indicating that this credential is for use with the Scholars platform, and select “Harvest” from the Type dropdown.
You have now created a Harvest API key! Keys are created without permissions by default, so you’ll have to click “Select All” to give the API key permission to access your data on Greenhouse. Your API key is the string of text in the blue rectangle with the key symbol; copy the key to your clipboard. Click the green “Update” button at the bottom of the page to save the changes to the API key.
Enabling the Greenhouse integration on the Scholars platform
Now that you have created a Harvest API key, you can enable the Greenhouse integration on Scholars. Make sure that the key is copied to your clipboard, and then enter your Scholars account. Click on “Integrations” in the left menu.
Once in the integrations section, click the “Greenhouse” tab. You’ll notice that the “API Key” field is marked “Incomplete”. Click the pencil icon to edit the Greenhouse integration configuration:
Once the editing is enabled, paste the API key from your clipboard into the “API Key” field:
Click “Save Information” to save your Greenhouse Harvest API key. The Scholars app will send a request to the Harvest API using the API key that you pasted in to verify that the key is valid. If the request is successful, the API key will be saved, and you should see it in the “Greenhouse Details” section:
Afterward, users will need to set the user to which we want the Scholars/Greenhouse integration to pertain to. They will accomplish this by going to their profile by selecting the My Profile tab on the left hand side.
There users are able to set the Greenhouse user account to which this integration will pertain to.
The user will accomplish this by entering the primary email to which their Greenhouse account is created with.
Afterwards, if they submitted a valid email, then their integration will be complete!
The user’s Scholars account is now capable of exporting candidates to Greenhouse!
Retrieve Scholars’s Endpoint URL and Secret Key
Before enabling the Greenhouse/Scholars integration, Greenhouse will need two pieces of information:
- Scholar’s Endpoint URL
- Scholar’s Secret Key
How to access Webhook Endpoint URL and secret key:
Once a user signs into their Scholars account they will see their account and be able to see a tab on the lower left hand side titled “Integrations”.
After a user clicks on the integrations tab, they are able to see their integration options, in this case they would select the Greenhouse tab at the top and there they have access to their Greenhouse integration settings.
As you can see, we display the webhook endpoint for easy access to the user, however we hide the API Secret for general security purposes but if the user needs to access it then they can press the pencil icon where users can edit their API Key input and also press on the eye icon to reveal the API Secret. The API secret is a randomly generated string, created by the Scholars application. This secret is used to sign HTTP requests sent to the webhook URL by Greenhouse, allowing the Scholars app to verify that HTTP requests are being sent to the correct Scholars accounts.
Enable Greenhouse/Scholars Integration
With Scholars’s endpoint URL and Secret Key copied, and your Greenhouse user permissions enabled, you are ready to enable the Greenhouse/Scholars. integration.
To enable the integration, click the Configure icon in the upper right-hand corner and navigate to Dev Center on the left-hand panel.
From the Dev Center page, click Web Hooks. Click Web Hooks from the subsequent page.
You will be directed to a new page where you Create a New Web Hook. From this page provide the following details:
- Name: we suggest Scholars Integration
- When: Be sure to select the right web hook so that the web hook fires at the appropriate event in Greenhouse
- Endpoint URL: The Endpoint URL received from the Scholars. Customer Success team
- Secret Key: The Secret Key received from the Scholars Customer Success team
When finished, click Create Web hook.
That's it! Your Greenhouse account and Scholars account can now talk to each other.
How to use the Scholars Integration with Greenhouse
Users are able to see all their Job Pipelines on the Pipeline tab of the Dashboard. Users will have already organized their candidates here.
After clicking on a pipeline card, they are led to a list of candidate/s that have been selected for a position.
There a user can set a default Greenhouse job for the list, upon which each exported candidate will attribute itself to on the Greenhouse platform.
After the user clicks there, a modal appears where they can set the job.
Then, users can quickly export their candidates to the Greenhouse platform by clicking on the Greenhouse icon on the right.
The candidate is now on the Greenhouse platform!
Optional Next Steps
After using the integration, you may decide you want to share more info between Greenhouse and Scholars. If you would like additional information transferred over, please reach out to Scholars Development Team (email@example.com) with a list of items to add and our team will review your request!
Please contact firstname.lastname@example.org for troubleshooting assistance regarding the integration.