Criteria HireSelect Harvest API integration

Criteria is a leading provider of web-based, pre-employment testing services. Criteria's mission is to make high-quality pre-employment testing solutions accessible to companies of all sizes. The HireSelect testing system is a SaaS (software as a service) solution that enables organizations to better manage their most important asset — their human capital — by providing state-of-the-art assessment tools to increase the effectiveness of the employee selection and retention process. HireSelect features aptitude, personality, emotional intelligence, and skills tests. 

Greenhouse Recruiting's integration with Criteria (HireSelect) allows users to send assessments and receive results in Greenhouse Recruiting via Harvest API. In this article, we will cover how to:

Request Assessment API Key from Criteria

To start, contact your Criteria Customer Success Manager to receive your API key. Once you have received your API key, fill out the form at 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.

Configure User Setup Permissions and Retrieve User ID in Greenhouse Recruiting

In order to enable the Greenhouse Recruiting / Criteria HireSelect 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 who should have access to set up the integration.

You will need to provide Criteria with the user ID for the On-Behalf-Of header. The user should have access to the Developer Permission Can manage ALL organization's API Credentials as illustrated above. To retrieve the user ID, from the User page, navigate to the URL and copy the number provided there. 


Save this user ID to provide to the Criteria team in a later step. 

Note: In order for results from Criteria to appear in the candidate records in Greenhouse Recruiting, the user ID provided to the Criteria team will need to continue to be a valid user. If the user becomes no longer valid (is deactivated, etc.) test results will stop appearing until a new valid user ID with permissions to Candidates and Custom Fields is provided to Criteria.

Create Harvest API Key for the Greenhouse Recruiting / Criteria HireSelect 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 Criteria.


In the Create New Credential dialog box, make the following selections:

  • API Type: Harvest
  • Partner: Criteria
  • Description: Criteria Harvest API Key

When finished, click Manage Permissions to generate the Harvest API key and automatically assign it the appropriate permissions required by Criteria.


In the subsequent dialog box, click Copy to save your API key to your clipboard. Store the API key in a secure location to provide to Criteria in the next step. Click I have stored the API Key once you have copied and saved the key.

Note: You cannot access the full API key again after clicking I have stored the API Key. If you lose your API key and need to access it later, you must create a new API key, provide it to the integration partner, and then revoke access to the original key.


On the subsequent page, confirm the following permissions are assigned to your new API key:


  • Patch: Edit Candidate

Custom Field Options

  • Get: Custom field options

If any of the permissions above are not checked, place a check in the box next to the appropriate permission. Click Save when finished. 

Your Harvest API key for the Greenhouse Recruiting / Criteria integration is created and configured. You will provide the Harvest API key to provide to the Criteria team in a later step. 

Create Custom Fields

To create Custom Fields for the integration, click the Configure icon Configure.png in the upper right-hand corner. Navigate to Custom Options on the left-hand panel.


From the Custom Options page, click Candidates


From the Manage Candidate Fields page, click Add Field


Enter the following details: 

  • Field Name
  • Field Type

Click Save when finished.


After you have saved the new field, the Immutable Field Key will populate. Copy and save the the Immutable Field Key to provide to the Criteria team in a later step. 


Repeat this process for all fields that are needed. 

Once all fields are created, provide the following details to your Criteria Customer Success Manager so the can set up the integration: 

  • Harvest API Key
  • User ID for On-Behalf-Of header
  • Immutable Field Keys for custom fields

Add Criteria Stage to Job's Interview Plan

Once the Greenhouse Recruiting / Criteria HireSelect integration is enabled for your organization, you will be able to add the Criteria 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, navigate to Interview Plan on the left-hand panel. Scroll down the page and click + Add a Stage.


From the Add Stage dialog box, select the Criteria stage. When finished, click Add at the bottom of the dialog box to add the stage to the job's interview plan.


Configure the Criteria Stage

Once the stage has been added to the job's interview plan, click Edit.


Use the dropdown menu to select the appropriate test battery for the job.


Scroll down to the Graders and Notifications panel and select at least one Greenhouse Recruiting user to grade/review the assessments, then click Save


Note: If you would like to add additional testing to another stage, simply replicate the steps above. You may want to name the second testing stage something different so you can differentiate them (e.g. Criteria 2 instead of Criteria). To edit the stage name hover over the stage name and click the pencil icon.

Send and Review Criteria Test

When a candidate is moved into the Criteria interview stage, Greenhouse Recruiting will display a Send Test link on the candidate's profile. Click the Send Test link.


Note: When you send a test from Greenhouse Recruiting, the interview instructions actually are sent to the candidate by Criteria.

Use the subsequent dialog box to:

  • Confirm the email address of the candidate
  • Select which assessment / question set the candidate will participate in
  • Assign a grader

Click Send Test when finished. 


Note: Keep in mind that all configuration of the assessment itself, as well as the email template, will need to be handled in HireSelect. When you click Send Test from within Greenhouse Recruiting, the assessment instructions are actually sent by Criteria.

The test will send immediately and this message will display on the candidate's profile to confirm when testing was sent: 


The candidate will receive an email from Criteria to take the assessments.


Once the assessments are completed the Grader(s), Recruiter, and/or Coordinator (depending on how you have configured notifications in Greenhouse Recruiting) will receive an email notification from Greenhouse Recruiting. Click the hyperlinked here to be directed to the Candidate’s Interview Kit.


Click View Report to see a PDF of the candidate’s score reports.


Note: The data in the custom fields and the link to the score report appear immediately upon completion of the assessments.

To view data in the custom fields, navigate to the candidate's profile and click the Details tab. 



Send Criteria Corp Test in Bulk

Note: Candidates must be in the same job and in the same stage (e.g. Criteria) in order to send the test in bulk. 

Navigate to the All Candidates tab and click the Pipeline Tasks filter on the left-hand panel. 


In the Pipeline Tasks menu, click the Test Status dropdown menu and select To Be Sent


The list of candidates will be filtered to only those with tests to be sent. Navigate to the top right of the All Candidates page and click Bulk Actions


Check the boxes next to the candidates to whom you would like to send the test (or click Select All). Click Edit Selected (#) when finished. 


In the subsequent dialog box, click Send Tests


In the subsequent dialog box, review the details and click Send Test

Note: If you select a different test than that which is associated with the job req, an email notification will not be sent to the Grader from Greenhouse Recruiting when the results for those tests are completed.


Get Help

Please contact for troubleshooting assistance regarding the integration.