Turn is a better, faster, and more affordable, FCRA-compliant identity screening solution for businesses that engage 1099 workers.
Greenhouse Recruiting’s integration with Turn Technologies allows you to process background checks for candidates. In this article, we will cover how to:
Configure User Setup Permissions in Greenhouse Recruiting
In order to enable the Greenhouse Recruiting / Turn integration, you will need the following developer permissions:
- Can manage ALL organization’s API Credentials
- Can manage and configure web hooks
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 icon > 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 and Can manage and configure web hooks 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.
Create a Harvest API Key for the Greenhouse Recruiting / Turn Integration
To create a Harvest API key for the integration, click the Configure icon in the upper right-hand corner. Navigate to Dev Center on the left-hand 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 Turn Technologies.
From the Create new credential dialog box, give your API key a name and select Harvest from the Type dropdown menu. When finished, click Create.
On the Manage API Key Permissions page, please grant your API key the permissions listed below. When finished, click Update.
- Custom Fields
Your Harvest API key for the Greenhouse Recruiting / Turn integration is created and configured. Provide your Harvest API key to your Turn Technologies onboarding team so they can set up the integration.
Create a Greenhouse Recruiting User on Behalf of Turn
In order to log information from Turn to custom candidate fields in Greenhouse Recruiting (you will configure these fields in a later step) with the status of the background check process, Turn will also need a Greenhouse Recruiting user ID. The user associated with this ID will be listed as the user who provided updates to these values on behalf of Turn Technologies. This user should have a Site Admin permission level so Turn has permissions to send data back on any candidate.
To learn how to create a new user in Greenhouse Recruiting, click here.
Note: In order to create a new user, you must be a Site Admin, or a Job Admin with the user-specific permission Can invite new users to Greenhouse and reactivate disabled users.
Create the new user with the following details:
- Email address: [YOUR_COMPANY_NAME]email@example.com
- Permission: Site Admin
Click Save at the bottom of the page when finished.
That is it! Your Greenhouse Recruiting / Turn account is active and ready.
Configure Custom Candidate Fields
In order to allow Turn technologies to relay details for new candidates regarding their background checks to Greenhouse Communicating, you must create three custom candidate fields: turn_status, turn_id, and turn_url.
Click on the Configure icon in the upper right-hand corner and navigate to Custom Options on the left-hand panel.
Click Candidates under the Company Custom Fields section.
On the Custom Fields: Candidates page, click the Add Field button.
Create the following three custom candidate fields:
Create the Turn Webhook
Before enabling the Greenhouse Recruiting / Turn integration, Greenhouse Recruiting will need three pieces of information:
- Turn’s Endpoint URL
- Turn’s Secret Key
- Turn’s Secret ClientId
To retrieve this information, please contact the Turn Technologies support team at firstname.lastname@example.org. and provide the Harvest API key and the user ID created in the previous steps.
With Turn’s endpoint URL and Secret Key copied, and your Greenhouse Recruiting user permissions enabled, you are ready to enable the Greenhouse Recruiting / Turn webhook.
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 the Create a New Web Hook page. On this page provide the following details to create a webhook:
- Name: We suggest Turn Webhook Integration
- When: Be sure to select the correct action so the webhook fires at the appropriate event in Greenhouse Recruiting [Candidate has changed stage]
- Endpoint URL: The Endpoint URL received from the Turn Customer Success team
- Secret Key: The Secret Key received from the Turn Customer Success team
Click Advanced settings.... and provide the following information:
- Additional HTTP Header: Be sure to provide the correct attribute adding the Secret ClientID value [Example: greenhouse-client-id : SecretClientID]
When finished, Create Web hook.
That is it! Your Greenhouse Recruiting account and Turn account can now talk to each other.
Add Turn Stage to Job's Interview Plan
Once the Greenhouse Recruiting / Turn integration is enabled for your organization, you will be able to add the Turn background assessment as a stage in your job's Interview Plan.
To do this for an existing job, navigate to a job (All Jobs > Job Name) and click Job Setup from the job navigation bar.
From the Job Setup page, navigate to the Interview Plan on the left-hand panel. Scroll down the page and click + Add a Stage.
From the Add Stage dialog box, create the Turn BGC stage. When finished, click Add to apply the stage to the job's Interview Plan
Once the stage has been added to the job's interview plan, be sure any additional survey or interview is listed.
Note: Keep in the mind that all the Turn background check itself, as well as the email template, will need to be done in Turn dashboard.
Send and Review the Test
When candidates are moved into the Background Check stage, Greenhouse Recruiting will communicate this update automatically to Turn using the webhook you configured. Turn will immediately initiate the background check, and additional information will be added to the candidate's Details tab.
For troubleshooting assistance regarding the integration, please email email@example.com.
For questions about pricing and offerings, contact Turn's Sales Team by emailing firstname.lastname@example.org.