ClearStar provides employers and companies across the globe with pre-employment background check software, screening services, and tools they need to quickly, easily, and confidently welcome new individuals to their team.
ClearStar’s integration with Greenhouse Recruiting allows users to initiate candidate background screening directly from within Greenhouse, receive real-time status updates on screening progress, and access completed background check reports — all without leaving the Greenhouse platform. The integration uses Greenhouse’s Harvest v3 API with the OAuth 2.0 Partner Auth Code Grant flow.
Configure the ClearStar integration
Configuring the ClearStar integration requires steps in both Greenhouse Recruiting and ClearStar’s ScreenMeNow (SMN) platform. All Greenhouse steps must be completed by a Site Admin.
If you need assistance activating the integration, follow the steps in the Connect to Harvest v3 partner integrations support article as part of your setup.
Authorize the connection in ScreenMeNow
Who performs this step: Administrator initiates the connection in ScreenMeNow (SMN).
Complete the authorization in the following order:
Administrator logs in to ScreenMeNow and navigates to Integrations > Greenhouse in the left navigation menu.
Select the customer from the Customer dropdown, then click Connect with Greenhouse.
The customer’s Greenhouse Site Admin logs in and reviews the requested permission scopes, then clicks Authorize.
Connection status indicators in ScreenMeNow:
Connect with Greenhouse button is available: The customer does not have an active connection, or the authorization has expired and re-authorization is required.
Connect with Greenhouse button is disabled: The customer has an active, authorized connection. No action is needed.
Note: To prevent disruption, ensure at least one background check is initiated within any 14-day period for active customers, or contact connect@clearstar.net to coordinate a re-authorization if needed.
The following error messages may appear if the authorization cannot be completed:
- Customer is not set up in Integration Center: The selected customer does not have a Greenhouse configuration in ClearStar’s system. Contact ClearStar’s implementation team.
Configure webhooks in Greenhouse
Webhooks allow Greenhouse to notify ClearStar when a candidate reaches a specific stage, triggering the background check invitation. In Greenhouse, navigate to Configure > Dev Center > Web Hooks and create a webhook using the values below.
For the default Hire Candidate trigger:
- Name: ClearStar Web Hook API
-
When:
hire_candidate - Endpoint URL: Provided by ClearStar
- Basic Authorization Credentials (Advanced Settings): Username and password provided by ClearStar
Note: ClearStar also supports offer_created and offer_approved as trigger events. These can be configured during implementation if an earlier point in the offer workflow is preferred. Work with ClearStar to determine the right trigger for your organization.
Create the CLEARSTAR_BGC_PACKAGE custom offer field
This field allows the recruiter to select the background check package when marking a candidate as hired. Navigate to Configure > Custom Options > Company Custom Fields – Offers.
- Click +Add Field.
-
Field Name:
CLEARSTAR_BGC_PACKAGE - Description (optional): ClearStar Package — displayed as a tooltip when selecting a package
- Field Type: Single Select
-
Options: Enter the package values provided by ClearStar. Each option must follow the format
<PackageID>:<Package Name>(e.g., SLRT_11598: Verification Package). This applies to both Domestic and Global packages. - Check Required.
- Click Save.
- Verify the Immutable Field Key reads:
clearstar_bgc_package
Note: The Immutable Field Key is auto-generated and must read clearstar_bgc_package exactly. If it differs, the integration will not identify the selected package correctly.
Create the CLEARSTAR_BGC_ACCOUNT custom offer field
Required when a single Greenhouse tenant serves multiple ClearStar customer accounts. Navigate to Configure > Custom Options > Company Custom Fields – Offers.
- Click +Add Field.
-
Field Name:
CLEARSTAR_BGC_ACCOUNT - Description (optional): ClearStar Customer/Account Name
- Field Type: Single Select
- Options: Enter the customer account names provided by ClearStar. Each value must exactly match the customer name in ClearStar’s IntegrationCenter.
- Check Required.
- Click Save.
- Verify the Immutable Field Key reads:
clearstar_bgc_account
Fields read and written by the integration
The ClearStar integration reads the following candidate and offer fields from Greenhouse to populate the background check order, and writes background check status notes back to the candidate’s Activity Feed.
| Greenhouse Field | ClearStar / ScreenMeNow Field | Notes |
| Candidate first name | First name | |
| Candidate last name | Last name | |
| Candidate email | Email address | |
| Candidate phone | Phone / mobile number | Used for SMS invite if enabled |
| Candidate education history | Education records | Must be enabled by Greenhouse specialist |
| Candidate employment history | Employment records | Must be enabled by Greenhouse specialist |
| CLEARSTAR_BGC_PACKAGE (offer field) | Background check package | Format: <PackageID>:<Package Name> |
| CLEARSTAR_BGC_ACCOUNT (offer field) | Customer account | Must match IntegrationCenter customer name exactly |
| Job offices | Accounting code (location) | Optional — requires MapJobOfficeToAccountingCode setting |
Note: Employment history is not enabled by default in Greenhouse. Contact a Greenhouse specialist to activate it. If it is not enabled, candidates will enter employment history manually in the ScreenMeNow application.
Background check workflow step
The default trigger for the ClearStar integration is Hire_Candidate. This is an existing Greenhouse workflow step and requires no custom configuration. Ensure that users who initiate hiring decisions are configured with appropriate access to the Hire Candidate workflow step.
Use the ClearStar integration
Once the integration is configured and the OAuth connection is authorized, recruiters can initiate ClearStar background checks directly from within Greenhouse. The steps below describe the most common scenario using the Hire Candidate trigger.
How to trigger a background check
From the candidate’s profile, click Move Stage and select Offer, then click Manage Offer.
Click Create Offer to create the offer, then click Mark Candidate as Hired (or Accept Offer, depending on your workflow).
In the Accept Offer dialog, complete the two ClearStar custom fields:
CLEARSTAR_BGC_ACCOUNT — select the customer account.
CLEARSTAR_BGC_PACKAGE — select the background check package.
Click Save. This fires the configured webhook. ClearStar’s system authenticates to Greenhouse using the authorized OAuth access token and creates the background check order.
Candidate invitation
After the webhook fires, ClearStar sends the candidate an invitation to complete the background screening application in ScreenMeNow:
- Email: A link to the ScreenMeNow application, pre-filled with candidate data retrieved from Greenhouse (name, contact details, education and employment history if enabled).
- SMS (if enabled): If the candidate has a mobile number on file and the ClearStar integration is configured for text invitations, an SMS invite is also sent.
How to track background check status
All screening activity is recorded in the candidate’s Activity Feed in Greenhouse. ClearStar posts notes to the feed at each status change. Report status values are:
- In Progress – Candidate: Invitation sent; the candidate has not yet completed the application.
- In Progress – Vendor: Candidate has submitted the application; ClearStar is processing the screening.
- Complete: Screening is complete with no flags.
- Complete – Review: Screening is complete; the profile has been flagged for recruiter review.
If your organization uses the ClearStar scoring matrix, the following statuses may also appear:
- Complete – Eligible
- Complete – Decisional
- Complete – Not Eligible
Once the screening is complete, a report link appears in the Activity Feed. Clicking the link opens ClearStar’s secure portal where the recruiter can view the full report.
Additional resources
For additional information not covered here, reach out to ClearStar support at connect@clearstar.net or visit www.clearstar.net.
For implementation or configuration assistance, contact the ClearStar implementation team:
- Implementation: implementations@clearstar.net
- Ongoing support: connect@clearstar.net
Frequently asked questions
Can multiple webhook events be configured?
Yes. ClearStar supports hire_candidate (default), offer_created, and offer_approved. If multiple triggers are configured and a candidate already has an active background check order, ClearStar sends a reminder rather than creating a duplicate order.
Is global background screening supported?
Yes. ClearStar supports both Domestic and Global screening through this integration. Global packages must be configured in the CLEARSTAR_BGC_PACKAGE offer field. Contact ClearStar to confirm your available packages.
What if the CLEARSTAR_BGC_ACCOUNT value does not match ClearStar’s records?
If the account value does not exactly match the customer name in ClearStar’s IntegrationCenter, the background check order will not be created. Verify field option values with ClearStar before going live. For assistance, contact connect@clearstar.net.