Clinch integration

PageUp Clinch is a Recruitment Marketing system which provides customers with tools to attract, engage and nurture qualified talent at the top of the recruitment funnel.

PageUp's integration with Greenhouse Recruiting allows users to have the job advertisements published to their organization's Clinch hosted intelligent career site to allow candidates to search and apply for jobs. Customers can optionally allow candidates to submit their initial applications for jobs via an embedded application experience on the job advertisement. Finally, the candidate's progression through the recruitment process can be tracked within PageUp Clinch, which facilitates conversion reporting, as well as allowing for further nurture via Clinch's CRM functionality.

Configure the Job Posting and Candidate integration

Detailed instructions on how to configure the integration between Greenhouse and PageUp Clinch are available in PageUp's knowledge article which is available here, and additionally are listed below:

Setup of standard integration

Generating a Candidate Ingestion API Key within Greenhouse

• In Greenhouse, navigate to the API integrations page: https://app.greenhouse.io/configure/dev_center/credentials
• Click the Create New API Key button.
• Select Candidate Ingestion as the API type.
• Select Clinch from the Partners list.
• Fill out the description field, for example: Clinch.
• Copy the API key as you will need it later.

Generating a Candidate Ingestion API Key within Greenhouse (only required if using direct apply)

• Navigate to https://app.greenhouse.io/configure/dev_center/credentials.
• Click Generate new API key.
• In the Description field, enter Clinch Job Board.
• Set the Type as Job Board.
• Click Create.
• Under Job Board API, click to Copy the displayed token. 
  

Configuration within PageUp Clinch Recruitment Marketing

• From the side menu, under Integrations, click ATS.
• Click the New button.
• Click the Greenhouse logo.
• Complete the form details:
  • Name
  • Partner API Key: Enter the candidate ingestion API key you created earlier.
  • Harvest API Version: Select "v3".
  • OAuth scope version: Select "v2 (adds custom location support)".
  • Job Board API Key: Enter the job board API key from Greenhouse (only required if using direct apply).
  • Company Code: If unsure, refer to your Greenhouse documentation. By inspecting the URLs that begin with boards.greenhouse.io at the top of the page, you can find the code.

The URL is of the form https://boards.greenhouse.io/<company_code>.

For example: if your URL is https://boards.greenhouse.io/acmelimited, then your company code is acmelimited.

• How are locations chosen: Location data for a job can be read from the "Location Name", or in the event of multiple locations, the "Office Location".
• Import job questions: Select whether this should be enabled.
• Support internal jobs: Select whether this should be enabled. 

Warning: Only check this if you would like to display jobs that are posted internally and jobs that are posted both internally and externally. This is only recommended for use with internal careers pages. 

A Greenhouse job can have many job postings. A job that is posted internally and externally on Greenhouse will appear twice in Recruitment Marketing if both Support internal jobs and Support external jobs are selected.

• Support external jobs: Select whether this should be enabled. 

Warning: Only check this if you would like to display jobs that are posted both externally and jobs that are posted both internally and externally. This is only recommended for use with external careers pages.

• How is the Apply URL constructed? Apply URLs can be read directly from ATS job data, or in the event that the job data doesn't contain an Apply URL, they can be built from a template. 
  For example: https://app4.greenhouse.io/internal_job_board/{{job_post_id}}
• How are remote jobs identified? Select the field used to identify remote jobs.
• Regex to match remote job locations: Enter the regular expression to identify fully remote jobs.
• Regex to match hybrid job locations: Enter the regular expression to identify hybrid remote jobs.
• Identify hidden jobs using a jobs criteria: Use the job filtering language to specify which jobs should be hidden, e.g., ats_uid = "123" or department = "hidden".
• Import unknown candidates: By default, only candidates who have applied through the careers website will have their ATS data imported. Enable this setting to import all candidates in the ATS who have recently been updated.
• Greenhouse User ID: Necessary for API calls that require a user.
• Interaction Field ID: See below.
• Choose what phone number goes to the ATS during Direct Apply: By default, the phone number bound to the candidate will be sent to the ATS. By changing this setting, it is possible to always attempt to send the form submission phone number first, falling back to the candidate phone number.
• Only submit e164 validated phone numbers during Direct Apply: When this setting is enabled, only phone numbers that match e164 will be sent to the ATS.
• How often do you want to read jobs data from the ATS
• How often do you want to read candidate data from the ATS
• Sync translations: If the careers site will be translated into multiple languages, then enable this setting.

Click Save.

Authorize the Harvest v3 Integration

Once your new integration has been created, you will be able to see it in the list of ATS integrations in Recruitment Marketing.

You will need to authorize with Greenhouse before you can start running the imports. For this, click on the plug icon in the Actions column to connect your integration with Greenhouse.

When you click on the plug icon, you will be redirected to Greenhouse to initiate the authorization process. You will see a list of scopes (endpoints) that you will be giving PageUp Clinch access to. You will need to log in to Greenhouse by entering your email address and clicking on the button as per the screenshot below. It's strongly recommended that the person performing this action has Admin privileges in Greenhouse.

If the person logging in is a Greenhouse Admin, you will see another screen with a checkbox asking to authorize using a service account, which is recommended, so tick that box and click "Authorize".

Once the authorization process has succeeded, you will be redirected to the ATS integration list page in Recruitment Marketing with a message of "Greenhouse ATS integration connected successfully". The actions menu will show a success tick, meaning the integration is fully connected to Greenhouse.

Once the customer has successfully authorized, they will be redirected back to PageUp Clinch, and they will be able to see the successful authentication has occurred via the presence of the green status tick next to the integration details.

Optional – Direct Apply to Greenhouse configuration

Overview

If you use Greenhouse as your ATS and have a relatively basic application form, Recruitment Marketing can accept candidate applications. This can improve the candidate's experience as they complete the application on the same page as the job description and do not need to interact with Greenhouse.

This is achieved by a two-way integration:

• Recruitment Marketing retrieves jobs and the application form questions from Greenhouse.
• Application questions are displayed on an Apply Call-to-action. 
  
• Upon submission of the Apply Call-to-action, Recruitment Marketing will send the applicant details and completed application form to Greenhouse.

Any synchronized application form questions can be viewed when editing a job. To access:

• From the side menu, under Content, click Jobs.
• Next to the relevant item, click Edit Job.

Supported Greenhouse fields

Profile Questions:

• First Name: Mandatory field.
• Last Name: Mandatory field.
• Email: Mandatory field.
• Phone Number: Partially supported – Must be configured in Recruitment Marketing CTA. Answers are sent back to Greenhouse.
• Resume: Fully supported.
• Cover Letter: Fully supported.
• Location: Supported by RM but behind a feature flag on Greenhouse. Refer to the Set up candidate location field below for further details.
• Education (profile question set): Supported – Greenhouse education fields are supported (School, Degree, Discipline, Start date, and End date). You can customize which of these fields you want to display on the CTA. Optional/Required per question within the set is not supported.

Custom Application Questions:

• Short Textbox: Fully supported.
• Long Textbox: Fully supported.
• Single Select: Fully supported.
• Multi-select: Partially supported – Multi-select checkbox only. Multi-select dropdown is not supported.
• Yes/No: Fully supported.
• Attachment: Fully supported.

EEOC Questions:

• Gender: Fully supported.
• Race: Fully supported – Displayed as a dropdown to select the Race. Asking "Are you Hispanic/Latino?" is not supported.
• Veteran Status: Fully supported.
• Disability Status: Fully supported.

Direct Apply Configuration within Clinch

Contact PageUp to enable the functionality, then complete the following:

• In Recruitment Marketing, from the side menu, under Integrations, click ATS.
• Next to Greenhouse, click Edit.
• In the Job Board API Key field, paste the copied token.
• Select the Import job questions checkbox.
• In Direct Apply Education fields, check the fields you would like to include in your Direct Apply CTAs.
• Click the Save button.

Now, you can set up your CTA to use direct apply:

• From the side menu, under Content, click Calls-To-Action.
• Next to the relevant CTA, click the edit button (pencil icon).
• Tick the direct apply checkbox that reads "Will the candidate make a direct application from the call to action?" (This is only available for Apply URL CTAs.)
• Click the Save button.
• Next to the relevant CTA, click # field(s).
• Click the New button.
• Complete the fields, and in the "What type of field is it" drop-down, select Job Application Questions.
• Click the Save button.

To achieve a pilot launch of Direct Apply jobs, create a Direct Apply CTA, duplicate a job page template with the Direct Apply CTA, and leverage Job Page Routing to specify the pilot job.

Set up the candidate location field

This is a text field that you can include in your Direct Apply form to collect the candidate's address. The location field is behind a feature flag on Greenhouse, and that flag is disabled by default. If you cannot see this field on the job settings, contact Greenhouse so that they can enable the flag for you.

Selecting either "Optional" or "Required" on Location will automatically include this field in the CTA form (as seen on screenshot below) once the job is imported to Recruitment Marketing.

Miscellaneous set-up

Maintaining attribution: Adding Greenhouse tracking links

The Recruitment Marketing module works to deliver the best candidate experience pre-apply (i.e., its focus is on attracting, nurturing, and converting candidates), as opposed to managing applications.

If you are distributing your Recruitment Marketing-hosted jobs via the Greenhouse ATS and wish to avail of end-to-end source tracking and attribution, you can edit the Greenhouse tracking links to the relevant pages as follows:

• Navigate to https://app.greenhouse.io/jobboard.
• Next to the relevant jobs board, click Actions, then Tracking Link.
• Make your selection for Who gets credit, then choose the source for which you want to establish attribution from the Select a source drop-down.
• Click Create Link and note the short code, as below.
• When unpacked, the code will look similar to: https://company.career-pages.com/jobs/search?gh_src=29796c671
• Append the tracking code to any job post link, e.g., https://company.career-pages.com/jobs/channel-manager-emerging-markets-new-york-united-states?gh_src=29796c671 and share it.
• To ensure that this is configured correctly, visit the job page using the new URL and complete a test application. You should see that the gh_src is passed from the URL to the Greenhouse form. This will allow for the correct attribution in Greenhouse.

Greenhouse: Automatic sync of ATS candidate tags

For customers with an integration to the Greenhouse ATS, the tags attached to candidates within the ATS will now be automatically synchronized to the CRM profile of the corresponding candidate within Recruitment Marketing. If a tag is added or removed from the candidate's profile in the ATS, this will automatically update on their CRM profile the next time the candidate integration runs.

Data mapping

Whilst the standard integration doesn't add or edit data within Greenhouse on behalf of the customer, the optional ability to host the initial application form on the PageUp Clinch hosted career site does add candidate and application data to Greenhouse. This is done via the Job Board API though (Harvest v3 itself is read-only).

The specific data that is created is:

• Candidate identity (always sent): First name, last name, email and phone number
• Applicant-supplied documents (conditional): typically resume/CV and cover letter and any additional file uploads the customer has configured on the Greenhouse job
• Application context (conditional, depending on the customer's integration settings): mapped_url_token, applicant_ip, location, latitude and longitude
• Answers to job-specific questions configured in Greenhouse: with values matching the question type
• EEOC / Demographic answers (conditional)
• GDPR consent (conditional)

The integration performs no update, patch, or delete against Greenhouse. Existing candidates and applications in Greenhouse are never modified by PageUp/Clinch. The only write is the initial POST that creates the application.

The standard integration pulls the following data from Greenhouse:

• Job postings
• Candidate status updates
• Candidate profile, including tags
• Application form configuration

The mapping is Greenhouse → PageUp Clinch, as all flows are read-only into PageUp. The outbound direction (PageUp Clinch → Greenhouse) is limited to the application POST covered in the previous question.

Most entities match the name in Greenhouse, except the ones outlined below. At a high level, these are:

• Job postings:
  • Department → JobDepartment
  • Category → JobCategory
  • Employment Type → JobEmploymentType
  • Salary range → JobSalaryRange
• Candidate status updates:
  • Application → JobApplication
  • Stage / rejected / hired state → CandidateEvent + CandidateEventAtsEvent
  • Stage name → AtsStatus
• Candidate profile:
  • Attachments → CandidateFile
  • Tags → CompanyTag
  • Education history → Education
  • Employment history → Employment
• Application form configuration:
  • Application questions → JobQuestion
  • Answer options → JobQuestionOption

Use the Job Posting and Candidate integration

Generally speaking, the integration operates automatically with no direct action required from the customer's user beyond the initial configuration.

The synchronization of jobs from Greenhouse into PageUp Clinch happens in the background via a batch process, with no direct user interaction. The synchronization runs on a recurring schedule, and can be configured to run anywhere between every 15 minutes up to every 6 hours.

Additionally, candidate status updates, as well as the key elements of the candidate's profile from Greenhouse are pulled in automatically by a background process, with no direct user involvement needed.

The user can manually trigger a job and/or candidate sync if needed, in addition to the scheduled recurring sync by clicking on the relevant option as per screenshot below.

The optional third element of the integration is the ability to host the candidate application on the job description page on the Clinch hosted career site.

The action of pulling the application form configuration into PageUp Clinch occurs automatically as part of the synchronization of the job postings noted above.

The user can view a read-only representation of the question assigned to each job via the job page within PageUp Clinch:

When enabled by the customer, the application form appears on the job description page (based on the layout defined by the customer), and is present to candidate as per this example:

Once submitted, the candidate receives a confirmation message, and information on next steps.

Additional resources

For additional information not covered here, reach out to:

• support@pageuppeople.com
• partners@pageuppeople.com

Useful resources:

• Overall Greenhouse article on PageUp Knowledge Portal
• Dedicated migration to Harvest v3 guide
• Link to demo video