SHL is a global talent intelligence company built on people science, helping organizations turn deep insight into their workforce into confident, objective decisions. With over 40 years of experience, SHL draws on one of the largest talent data sets in the industry, developed by a team of more than 300 people scientists, to power its assessments. SHL's assessments — spanning cognitive ability, personality, behavioural, and situational judgment testing — are used by more than 10,000 organizations worldwide across virtually every industry and job level and integrate with 80+ applicant tracking systems.
Built on the Greenhouse Harvest v3 API, the SHL integration brings assessment into the hiring pipeline itself. Moving a candidate into the assessment stage is enough to get an assessment out to them — no separate SHL session needed. From there, recruiters can track where a candidate stands and pull up their results without leaving the candidate's Greenhouse profile. When a score changes on SHL's side, Greenhouse reflects the update automatically, so the full picture — from application to offer — stays in one place.
This guide explains how to configure the SHL integration with Greenhouse Recruiting using the Harvest v3 API, OAuth 2.0, and webhooks.
Configure the SHL integration
Prerequisites
- You must have SHL assessment packages configured with your SHL account.
- You must have a Greenhouse account with Site Admin permissions, or permissions to manage the organization's API credentials, to authorize the connection.
Connect with Greenhouse
Use the following steps to connect your SHL account to Greenhouse Recruiting using the Harvest v3 OAuth:
Contact your SHL representative to initiate the Harvest v3 OAuth connection.
Your SHL representative will enable the connection and provide an authorization link through secure email.
The link will redirect you to Greenhouse and prompt you to log in with your Greenhouse credentials.
Review the permissions SHL is requesting.
Choose whether to authorize using a Greenhouse service account or your individual user account, then click Authorize.
After you authorize, your SHL account is connected to Greenhouse Recruiting using the Harvest v3 OAuth.
Verify the connection
Once authorized, you can confirm the integration is active from Greenhouse Recruiting:
- Click the Configure/Settings icon (top right) in the Greenhouse navigation bar, then click Dev Center.
- Click Connected Integrations.
- Confirm that SHL Assessments appears in the list with a Connected status.
Set up custom stages
Before sending assessments, work with your Greenhouse representative to add the following custom stages to your hiring pipeline. These stages must be created in Greenhouse and cannot be created through the SHL integration.
- Send SHL Assessment — Candidate can be placed here manually by a recruiter to initiate an assessment, or SHL will move the candidate here automatically if automatic progression is enabled.
- Pending SHL Assessment — Once assessment registration is complete, SHL will move 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, and the candidate is moved to the Completed SHL Assessment status.
- Error SHL Assessment — SHL moves the candidate here if an issue occurs with the assessment invitation, such as an invalid email address.
Set up custom fields
This integration requires several custom fields to allow for assessment integration.
Note: Custom fields are immutable, so deleting a field once created and trying to recreate it with the same name will not work. If you need to delete and recreate a custom field, contact Greenhouse Support for assistance.
There are two types of fields required:
- Custom Job fields
- Custom Application fields
Job custom fields
To configure these custom fields, go to the configuration page in Greenhouse: Settings > Custom Options > Under Company custom fields – Jobs.
The only job-level custom field is shl_assessment_tag — which stores the assessment package tag used by SHL to identify the assessment to be assigned to candidates for the job/application. The field name must match exactly so the SHL integration can recognize it.
Any field name beginning with shl_assessment_tag will be recognized by the SHL integration, allowing you to configure multiple assessment package tags.
Note: This field is only read during initial registration, not on follow-on updates.
Click Add Field.
Fill in the following fields as shown below:
Field Name: shl_assessment_tag
Description: Optional description of the field.
Field type: Set to Short textbox. This can be set to a drop-down list (single-select) if preferred, but it will then need to be managed on the client's side.
Option 1: Short textbox
Option 2: Single select — add package tags in Options, each on a new line.
Select Create new email token.
Select Mark Required.
Similarly, you can add more custom fields named shl_assessment_tag_1, shl_assessment_tag_2, and so on, and add the information and field values to them as required.
Application custom fields
To set up the second type of custom fields, go to this section of the Application Custom Fields in Greenhouse: Settings > Custom Options > Under Company custom fields – Applications.
Not all custom fields shown here need to be created — the screenshot above is only an example.
For each candidate application, various custom fields are used both to read what assessment to register the candidate and to set the current status. These are the keys that need to be configured so they can be read from and written to:
shl_assessment_tag: This is the field that holds the assessment.
Option 1: Short textbox
Option 2: Single select — add Package Tags in Options, each on a new line.
Similarly, you can add more custom fields named shl_assessment_tag_1, shl_assessment_tag_2, and so on, and add the information and field values to them as required.
shl_candidate_url: Upon successful registration, the unique link for the candidate and assessment will be sent to this field. This is not directly used by Greenhouse but is more informational for the recruiter — for example, if a candidate misplaces the email assessment invitation.
shl_overall_status: Upon successful registration, this field will be set to a simple success message; otherwise, it will show an error message sent by SHL. This information can help the recruiter identify assessment registration issues.
shl_reports_url: When assessment results are returned to Greenhouse, SHL provides the URL to access the candidate report.
shl_ignore (optional): You may choose to configure this field so that during bulk or automatic operations, you have a way to indicate that a particular application should be ignored. If the value is set to true or 1, the notification will be ignored.
overall_score: For each score that needs to be returned, a custom field with the same name will need to be created. For example, if you want to return a score called overall_score, that custom property will need to be configured within Greenhouse.
Set up webhooks
The notification Greenhouse sends to SHL is called a "Webhook," which is why the integration has that name. This is basically just the notification of an event and includes a secret key for authentication.
During candidate registration and when assessment results are returned to Greenhouse, the integration makes requests using the Harvest API to get and update data on the candidate.
A Webhooks notification is triggered upon a status change to a candidate. This can be a completed application, or an action taken by a recruiter. A completed application can trigger a Webhook notification that sends a candidate registration event to SHL.
The Greenhouse "Webhooks" notification method is used and is configured at Settings > Dev Center > Webhooks.
How to configure your webhooks:
- The name of the webhook can be anything.
- The trigger needs to be "When candidate has changed stage".
- The endpoint URL includes the client ID, so it's different for each client. SHL will provide the client-specific endpoint URL during integration setup.
- The secret key can be set to any string (for example, "greenhouse secret key"). Provide the secret key to your SHL representative through the agreed secure channel.
Note: Greenhouse sends a test message to verify that the webhook endpoint is valid. If the endpoint does not return HTTP 200, Greenhouse will not enable the webhook.
Data mapping
| Greenhouse Field | SHL Usage | Direction | Description |
shl_assessment_tag |
Assessment Package Tag | GH → SHL | Identifies the SHL assessment package to register |
shl_candidate_url |
Assessment URL | SHL → GH | Stores the candidate's assessment link as generated by SHL |
shl_overall_status |
Registration Status | SHL → GH | Stores candidate's status |
shl_reports_url |
Report URL | SHL → GH | Stores the candidate report URL |
overall_score |
Assessment Score | SHL → GH | Stores the returned assessment score |
Use the SHL integration
When the candidate is moved to the Send SHL Assessment stage, SHL registers the candidate and sends the assessment invitation using the candidate's email address. Once the candidate completes the assessment, the results are returned to Greenhouse.
Send an SHL assessment
In the candidate's profile, click Move stage and select Send SHL Assessment.
Candidate completes the assessment
Once the candidate is moved to this stage, they receive a link to begin their SHL assessment(s).
View assessment results and reports
Click Application (right side ribbon). You can check the candidate's assessment scores and the final report generated.
Additional resources
For additional information not covered here, or for help troubleshooting the integration, contact SHL Integration Product Support: IntegrationSupport@shl.com or alliances@shl.com.