Xref is an automated reference checking software that helps you gather high quality insights, in less time.

Greenhouse Recruiting's integration with Xref allows you to seamlessly add Xref reference checks to a job's interview plan. In this article, we will cover how to:


Configure User Setup Permissions in Greenhouse Recruiting

In order to enable the Greenhouse Recruiting / Xref integration, you will need the developer permission Can manage ALL organization’s API Credentials.

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 Configure.png  > 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 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 / Xref Integration

To create a Harvest API key for the integration, click on the Configure icon Configure.png 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 Xref. 


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, grant your API key the following permissions: 

  • Applications
  • Candidates
  • Users


When finished, click Update.

Your Harvest API key for the Greenhouse Recruiting /Xref integration is created and configured. Copy and save the Harvest API key to provide to your Xref onboarding team. 


Retrieve Greenhouse Recruiting User ID

Next, you will need to identify the user ID of a Site Admin for your organization. Click on the Configure icon Configure.png in the upper right-hand corner, and then click Users in the left-hand panel. 


From the Users page, click Export to Excel


An .xlsx file will be downloaded to your computer. Open the spreadsheet and navigate to the User ID column. Copy a Site Admin user ID from the column. Provide this user ID to your Xref onboarding team along with your Harvest API key generated in the previous step. 


Enable the Greenhouse Recruiting / Xref Integration

Contact the Xref Integrations Team by emailing integrations@xref.com to receive your Xref API key. Once you have received your API key, fill out the form at www.greenhouse.io/asksupport or click here to open a ticket. 

Note: Do not send the API key in this initial email.

The Greenhouse Support Team will respond with a SendSafely link for you to enter your API key. A notification will be sent to the Greenhouse Support Team after you have entered your API key and they will email you to confirm that your API key has been set up in your account and your integration is enabled.

Note: To verify your identity, the Greenhouse Support Team might request you provide a Support Verification Code before adding the API key to your organization's account.


Add Xref Stage to Job's Interview Plan

Once the Greenhouse Recruiting / Xref integration is enabled for your organization, you will be able to add the Xref assessment as an interview stage. 

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, click Interview Plan in the left-hand panel. Scroll down the Interview Plan page and click + Add a Stage


From the Add Stage dialog box, select the Xref stage. When finished, click Add to apply the stage to the job's interview plan.



Configure Xref Job Stage

On the Interview Plan page, find the newly added Xref stage and click Edit Take Home Test next

Once the Xref stage has been added to the job's interview plan, click Edit. Use the provided dropdown to select the assessment to be sent from a list of assessments you previously configured in Xref. 


Select the appropriate assessment and assign at least one Greenhouse Recruiting user to grade/review submitted assessments. When finished, click Save at the bottom of the page.

Note: Keep in mind that all configuration of the assessment itself must be completed in Xref. 


Send and Review Xref Test

When candidates are moved into the Xref interview stage, Greenhouse Recruiting will display a Send Test link on the candidate's profile. Xref requires a Recruiter source against the candidate in order to create the check and attribute the request to a user. 

Note: When you send a test from Greenhouse Recruiting, the assessment instructions are actually sent by Xref. 

xref.png Once the test has been sent, the status of the test will be viewable in Greenhouse Recruiting. 


Once the candidate has submitted their test, the scorecard page will contain a link to view the submitted test on Xref.


The Xref report also will be saved as a document that can be viewed from the candidate's Details tab > All Attachments section. 



Get Help

Please contact support@xref.com for troubleshooting assistance regarding the integration. Or visit Xref Support for frequently asked questions about the Xref employer, candidate, or reference process.