Note: The integration documented here is a newly-released improvement on the earlier version powered through Greenhouse Recruiting’s Ingestion API. If your Handshake account is already set up with the older solution, that will continue to function after the new integration is established for all pre-existing job posts in Handshake. Once the setup steps described below are complete, the new integration will be used for all new jobs in Handshake moving forward. Connect with your Handshake contact to learn more.
If your organization is enabling the Greenhouse Recruiting / Handshake integration for the first time, we recommend enabling the version documented in this article.
Handshake is a college career network, built to transform the recruiting experience for college students, career centers, and employers. Handshake's mission is to democratize access to opportunity: to help every college student find the right job for them, no matter where they go to school, what they're majoring in, or who they know. Handshake offers powerful sourcing tools, both free and premium, for employers to engage with these candidates.
Greenhouse Recruiting’s integration with Handshake, a premium Handshake feature, allows your team to:
- Provide your recruiters with a more efficient job posting process
- Streamline the applicant experience by letting them directly apply on Handshake
- Complete your hiring activities in one system by reviewing applicant information collected in Handshake, including custom application questions and other applicant details, directly in Greenhouse Recruiting
- Keep up to date on how your applicants are moving through the interview process within Handshake
In this article, we will cover how to:
- Configure User Setup Permissions in Greenhouse Recruiting
- Share User ID with Handshake
- Create a Harvest API Key for the Greenhouse/Handshake Integration
- Create a Job Board API Key for the Greenhouse/Handshake Integration
- Configure your Job Board
- Set up Handshake’s tracking code in Greenhouse
- Set up webhooks in Greenhouse
- Sync jobs from Greenhouse Recruiting to Handshake
- Support direct applications from Handshake into Greenhouse
- Review Handshake applications in Greenhouse and sync to Handshake
Configure User Setup Permissions in Greenhouse Recruiting
In order to enable the Greenhouse/Handshake integration, you will need the developer permissions Can manage ALL organization’s API Credentials and 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 both checkboxes. When finished, click Save.
Repeat as necessary for any other user that should have access to set up the integration.
Share User ID with Handshake
In order for Handshake to allow candidates to apply directly to Greenhouse Recruiting, Handshake will need the user ID of an existing Greenhouse user in your organization, or the user ID for a Greenhouse Recruiting user account that is created specifically for Handshake.
Note: For information on how to create a new user, click here.
To locate the user ID for either an existing user or for the new Handshake-specific user if applicable, click the Configure icon in the upper right-hand corner and select Users from the left-hand panel.
From the Users page, click Export to Excel.
A spreadsheet will be downloaded to your computer. From the spreadsheet, navigate to the User ID column and copy the user ID value inline with your selected user.
Share the User ID with your Handshake representative.
Create a Harvest API Key for the Greenhouse/Handshake Integration
To create a Harvest API key for the integration, click on 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 Handshake.
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, select all of the following API permissions.
GET: Retrieve Application
GET: List Applications
PATCH: Update Application
GET: List Candidates
GET: Retrieve Candidate
POST: Add Candidate
POST: Add Note
POST: Add Attachment
POST: Add Application
POST: Add Education
POST: Add E-mail
PATCH: Edit Candidate
GET: Get degrees
GET: Get disciplines
GET: Get schools
GET: Retrieve Job
GET: List Jobs
GET: List Job Posts
GET: Retrieve Job Post for Job
GET: List Job Posts for Job
GET: List Sources
When finished, click Update.
Your Harvest API key for the Greenhouse/Handshake integration is created and configured. Provide your Harvest API key to your Handshake onboarding team so they can set up the integration.
Generating Job Board API Key:
- Click on the Configure tab
- Select Dev Center > API Credential Management
- Click Create New API Key to generate the API key for Handshake
- Select the API Key type as “Job Board”
- Send the generated API key to your Handshake onboarding team via a secure method so they can set up the integration
Configuring your Job Board
For Handshake to be able to submit applications, you will need to find them your job board token. To receive the job board token, complete the following steps:
- Click on the Configure tab
- Select Job Board
- Click Edit
- The job board token will be located in the URL field
- For example: CompanyABC’s board token is "companyabc" with the URL being https://api.greenhouse.io/v1/boards/companyabc/jobs
Setup Handshake’s tracking code in Greenhouse:
Please sign into Greenhouse to generate your Handshake tracking code.
Go to Configure > Job Board > Actions > Tracking Link.
From the “Select a source” list, type or select Handshake, then click the "Create Link" button. Copy the alphanumeric code at the end of the URL that is generated and provide to your Handshake onboarding team.
If your Greenhouse create account does not have Handshake as an available source, go to Custom Options > Sources > Create New Source. Add Handshake as a source so that you can create tracking links for any candidates coming through Handshake.
Set up Handshake webhooks in Greenhouse
Webhooks allow Greenhouse to send secure messages directly to Handshake whenever changes occur with your Greenhouse jobs and candidates. To configure your Greenhouse webhooks, first navigate to the “Web Hooks” page in the Greenhouse developer center (https://app.greenhouse.io/web_hooks). You should be brought directly to the form for creating a new webhook.
The following settings will use the same values for every webhook you create:
Endpoint URL: https://ats.joinhandshake.com/webhooks/greenhouse/<handshake_employer_id>
Secret key: Enter the secret key provided by your Handshake onboarding team
Error recipient email: leave blank
Username: leave blank
Password: leave blank
Additional settings: leave blank
Each of the following features will be enabled automatically when you create a webhook with the given value for the “When” field:
- When I create a new job post in Greenhouse, I want Handshake to have that job available for me to post to schools.
- Name this webhook: post_created_handshake
- When: Job Post Created
- When I update a job post in Greenhouse, I want Handshake to have the most up-to-date details on that job post.
- Name this webhook: post_updated_handshake
- When: Job Post Updated
- When I close a job in Greenhouse, I want Handshake to update its list of jobs to only include live job posts.
- Name this webhook: job_updated_handshake
- When: Job Updated
- When candidates move through the hiring workflow in Greenhouse, I want to update their statuses in Handshake.
- Name this webhook: hire_candidate_handshake
- When: Candidate has been hired
- When a candidate is rejected in Greenhouse, I want to update their statuses in Handshake.
- Name this webhook: candidate_rejected_handshake
- When: Candidate or Prospect rejected
Sync Jobs from Greenhouse Recruiting to Handshake
In Handshake, follow the process to create a new Handshake job, or to edit an existing job (that does not have any applications yet).
Use the Select Greenhouse job to link dropdown to select from a list of jobs available in your Greenhouse Recruiting account. Select the job you wish to link.
Note: Existing jobs in Handshake cannot be linked to Greenhouse Recruiting. If you wish to sync applications for an existing job, please expire the job and re-post.
When a job is selected, Handshake will also retrieve the following details from Greenhouse to make the posting process more efficient:
- Job Details
- Number of Positions
- Employment Type
- Paid / Unpaid
- Required Documents
Post your Handshake job to Schools by filling out the rest of the job details, and choosing the schools to post the job to.
Once you have posted the job to schools, you are finished! To learn more about the job-posting process in Handshake, please see the following Handshake Help Center article: How to Post a Job.
Support Direct Applications from Handshake
Students will browse Handshake and find your jobs. For more information on how students find jobs in Handshake, please see the following Handshake Help Center article: How to Search for Jobs & Internships.
Once a student finds your job, they can click to apply for it in Handshake. Students will have the ability to upload a resume and/or cover letter as specified on the job post. They will also see the required and optional questions configured in Greenhouse.
Once the required details are entered, students will directly submit their applications to Greenhouse Recruiting via Handshake.
Review Applications in Greenhouse Recruiting and Sync to Handshake
Once a student has applied in Handshake to a linked job, the student's application will appear in Greenhouse Recruiting automatically within a few minutes. The application will include the candidate's first name, last name, and email address. The application will show the candidate's Source as Handshake, and also will include the candidate's resume and cover letter (if required for the application process) under the Application or Details tab > Source & Responsibility section. The Application will also include the responses provided for any required or optional Job Post Questions.
The Greenhouse Recruiting / Handshake integration uses real-time application status syncing, which means you will see applicant statuses update in Handshake as they are hired or rejected in Greenhouse Recruiting. This status updates within moments of being updated in Greenhouse.
With these statuses synced, you will be able to more accurately source new applicants and analyze past recruiting efforts
Please contact firstname.lastname@example.org for troubleshooting assistance regarding the integration.