Enabling and using the Turn integration

Available for User roles Super Admin, Admin, Team Member, Limited Team Member
Can only be configured by Super Admins
Packages All packages

Turn’s Lever integration makes it easy for you to begin processing background checks on candidates directly from Lever’s interface.

Simply by moving a candidate to a specified stage in your recruitment pipeline, you can automatically trigger Lever background checks. You will also be able to keep track of the status of your background checks from within Lever.

Setup the integration:

Note: Access role must be Super Admin in order to set up the integration.


From within your Turn partner dashboard’s settings page, you can authenticate your connection with Lever in just a few clicks.

Turn settings page with Lever integration card outlined.

In the settings page, you will see a button for authenticating Turn to make changes to your Lever account.

Turn platform showing Lever integration with authorize Lever label.

Simply expand the Lever Integration section and click Authorize Lever. You will be redirected to Lever’s login page where you can grant access.

Turn will request access to see and edit your opportunities, read your pipeline stages, and your tags.

How to configure the integration:

In order for Turn to know when your opportunities change stage in your recruitment process, you will need to set up webhooks. This means that whenever an opportunity moves to a new stage, a notification will be sent to Turn.

1. To set up a new webhook, click Settings in your Lever account, then navigate to Integrations & API and click the Webhooks tab. 

2. On this tab, you can enter your webhook url. This can be found on the /settings page of your Turn partner dashboard.

Turn platform with Lever integration modal.

3. Copy and paste your Lever Webhook URL from Turn into the Lever webhook form.

Lever webhook section with webhook field and signature token outlined.

4. Copy your Lever webhook signature token, copy it to the “Webhook Secret” field in Turn. Click Save

It is very important that your webhook secret is saved so that we can check that the webhooks that we receive are coming from you.

How to use the integration:

When to start a background check

Turn will receive a webhook whenever any of your opportunities change stage. In order to make sure that background checks only take place when you want them to, we recommend that you specify a stage name for when to trigger a background check.

Paste the name of your trigger stage into the “Background Check Pipeline Stage” input field and click Save. Turn will ignore any notifications from Lever unless the opportunity is moving into your specified stage.

Lever integration modal in Turn platform.

By default, “Reference Check” is selected as the trigger stage. If you would like to add additional stages to your recruitment pipeline, please contact Lever support.

Choosing your package

The background check package which will be run on your opportunity is determined by the tags that you associate with the opportunity record in Lever.

If you are not sure about which packages apply to your Turn account, please feel free to contact Turn support at support@turning.io and we will provide you with a list of tags which you can add to your account.

Lever candidate profile with turnpackage tag.

Turn package tags will follow this format: TurnPackage:{PACKAGE_ID}:{PACKAGE_NAME}.

We recommend that you configure all of your relevant package tags in your Lever account settings in order to make sure that there is no danger of misspellings or typos. You can find this page by visiting the settings page of your Lever account and navigating to Sources and tags (see image below).

Lever sources and tags page.

If no valid package tag is applied to a candidate when it moves into your designated pipeline stage, your Turn account’s default background check package will be applied.

Updates in Lever

When an opportunity in Lever is being processed in Turn, you will notice that a new note is added to the opportunity page. This note contains the opportunity’s Turn ID for your reference.

Lever candidate profile with turn ID listed.

You will also be kept informed about the opportunity’s background check status via tags.

Turn will keep updating the opportunity’s tags as the background checks progress. You will be able to identify these tags because they will follow the format TurnStatus:{STATUS}.

Lever candidate profile showing turnstatus.clear tag.

Once an opportunity has an available background check report, the url to this report will be added to the opportunity record as a note.

How to disable the integration:

1. Navigate to your Integrations & API Settings Page in Lever.

2. Under the Authorized Apps tab locate the Turn app.

3. Click Revoke Access to disable the integration.

Any questions?

Please feel free to reach out to Turn support at support@turning.io.

Was this article helpful?
0 out of 0 found this helpful