SHL is the global leader in talent innovation, helping more than 10,000 companies transform productivity through deeper people insight. Powering the future of business, SHL's data and tools are proven to drive stronger, more sustainable business outcomes.
SHL's web hook integration with Greenhouse Recruiting provides recruiters and hiring managers with an easy way to assess candidates as part of the candidate workflow.
Note: The SHL web hook integration is only available for organizations with an Advanced or Expert Greenhouse subscription.
Overview
With the SHL web hook integration, a recruiter can manually trigger a specific assessment for a candidate. SHL will send an email to the candidate to complete the assessment, and when complete, Greenhouse Recruiting will share the assessment results on the candidate's Details tab.
Note: There is a separate SHL integration called SHL (TalentCentral) integration that will automatically launch an assessment as soon as an application is submitted, or at a specific step in the interview plan in Greenhouse Recruiting. The candidate will receive an email after applying or as soon as a recruiter moves them to a specific stage. Your organization can decide which of the two SHL integrations works best for your hiring processes.
Enable the SHL web hook integration
Create a Harvest API key
To enable the Greenhouse Recruiting / SHL integration, you'll need to create a Harvest API key.
Follow the steps in this article to create the key, and verify that the credentials and permissions below are selected.
Credentials
In the Create New Credential box, make the following selections:
- API Type: Harvest
- Partner: SHL
- Description: SHL Harvest API key
Permissions
Verify that the following permissions are selected for the integration:
Applications
- All permissions
Custom fields
- GET: Get custom fields
Job stages
- GET: List job stages for job
Jobs
- GET: Retrieve job
When finished, click Save.
Your Harvest API key for the SHL integration is created and configured. Provide the Harvest API key to your SHL representative.
Retrieve your Greenhouse Recruiting user ID
In order to provide updates directly in Greenhouse Recruiting, SHL requires the user ID of a Greenhouse Recruiting user to associate with integration updates.
You can create an integration system user (ISU) in Greenhouse Recruiting specifically for SHL, or you can share an existing person's user ID.
Using either method, follow the steps in this article to retrieve a user ID and share it with the SHL team.
Create a web hook
Note: Before configuring the integration's web hook, make sure you've received your organization's unique endpoint URL from SHL.
To integrate SHL with Greenhouse Recruiting, you'll need to create a web hook. Follow the steps in this article to create your web hook. Use the values listed below.
- Name: SHL integration
- When: Candidate has changed stage
- Endpoint URL: The unique endpoint URL received from SHL
- Secret key: Enter any string of characters, such as greenhouse secret key. The secret key must be shared with the SHL team after creating the webhook.
When finished, click Create Web hook.
Create custom fields
The SHL integration requires several custom job and application fields in Greenhouse Recruiting.
Custom job field
Follow the steps in this article to create a custom job field, and use the following details when configuring the field:
- Field Name: shl_assessment_tag
- Field Type: Short textbox
- Create new email token: Yes
- Required: Yes
Note: Be sure the field's exact name is shl_assessment_tag. This field will retain the external package tag value from SHL to be assigned to candidates for that job.
When finished, click Save.
Custom application fields
Next, follow the steps in this article to create six (6) custom application fields, using the following details:
| Field Name | Field Type | Where should this field show up? | Create new email token | Mark Private | Additional details |
shl_assessment_tag |
Short textbox | Candidate | Yes | Yes | This field that holds the assessment / IC external package tag. It's possible to have multiple package tags. |
shl_candidate_url |
Short textbox | Candidate | Yes | Yes | This field is not directly used by Greenhouse Recruiting, but is informative to the recruiter, for example if a candidate misplaces the email assessment invitation. |
shl_overall_status |
Short textbox | Candidate | Yes | Yes | This field is not directly used by Greenhouse Recruiting but is informative to the recruiter to identify an issue, or to assist SHL in troubleshooting if necessary. |
shl_reports_url |
Short textbox | Candidate | Yes | Yes | SHL provides the URL to access the link in candidate reports. |
shl_ignore (Optional) |
Some clients choose to configure this field so that during bulk or automatic operations they have a way to indicate that a particular application should be ignored. If the value is set to true or 1, then the notification is ignored. | ||||
SCORES |
Short textbox | Candidate | Yes | Yes | For each score that needs to be returned, a custom field with the same value needs to be created. For example, if you want to return a score called overall_score (or the client friendly name as configured by SHL) then such a custom field needs to be configured within Greenhouse Recruiting. |
Add SHL stages to an interview plan
Finally, you're ready to add the SHL stages to a job's interview plan in Greenhouse Recruiting.
Navigate to an existing job (Jobs > Job name), or create a new job.
Click the Job Setup tab, and then click Interview Plan.
Click Add stage.
Click the Create New Stage field and type Send SHL Assessment for the name.
Click Add.
Repeat this process to add three (3) additional SHL stages to your interview plan:
- Pending SHL Assessment
- Completed SHL Assessment
- Error SHL Assessment
For more details on how the stages are used, check out the table below.
| Stage name | Purpose |
| Send SHL Assessment | Candidates can be moved to the Send SHL Assessment stage by the recruiter to initiate an assessment manually. |
| Pending SHL Assessment | Once assessment registration is complete, SHL moves the candidate into the Pending SHL Assessment stage. This signifies the candidate has the link to take the assessment. |
| Completed SHL Assessment | Once the candidate completes the assessment, the scores and reports are returned to Greenhouse Recruiting and the candidate is moved to the Completed SHL Assessment stage. |
| Error SHL Assessment | If an issue occurs with the assessment invitation (such as a bad email address) SHL will move the candidate to the Error SHL Assessment stage. |
Once you create these stages and add them to one job, the stages will be available to add on additional jobs where you wish to use the SHL integration.
(Optional) Test the SHL integration
If you wish to test the SHL integration before using it with a live candidate, you can add a test candidate to Greenhouse Recruiting and move the candidate into the Send SHL Assessment stage. Use a different, valid email address for the candidate than the email address you use to log into Greenhouse Recruiting.
Note: When you add the candidate to Greenhouse Recruiting, be sure you initially add them to a non-SHL stage. Once the candidate is added, you can manually move them into the Send SHL Assessment stage.
Use the SHL integration with Greenhouse Recruiting
When a candidate is moved into the Send SHL Assessment stage, SHL will trigger an assessment and email the candidate a link to complete it.
The candidate will automatically be moved into the Pending SHL Assessment stage once they receive the link.
When the candidate completes their assessment, the scores and reports will be returned to Greenhouse Recruiting and the candidate can be moved to the Completed SHL Assessment stage.