Greenhouse - Beamery Integration - Technical Document

Terminology

Beamery	Greenhouse	Notes
Contact (prospect)	Prospect	Prospect not in any vacancy
Contact (candidate)	Candidate	Candidate in at least 1 vacancy
Vacancy	Job	Role in the company
Vacancy Stages	Interview Stage	Stages in a hiring process

Integration Overview

The Greenhouse Integration allows you to seamlessly combine sourcing and recruiting processes between Beamery and Greenhouse. In Beamery, you can view vacancies and a candidate's application state managed through Greenhouse. You can also push new contacts sourced in Beamery to Greenhouse. For a full list of features supported by this integration, please see the data flow diagram below.

The table below displays what actions are supported by the integration and in what direction.

	Greenhouse to Beamery	Beamery to Greenhouse
Vacancy
Create / Update Vacancy
Contact
Create Contact without vacancy
Create Contact with vacancy (application)
Update Contact
Block Confidential Candidate Updates (configurable)
Contact Attachment
Public Notes
Merge Contact
Anonymize Contact
Configuration
Create / Update Sources
Create / Update Profile / Candidate Tags

Vacancy Object

Greenhouse Jobs that are updated since the last sync in Greenhouse are imported to Beamery to create or update vacancies periodically (every 1-4 hours). The import is done by Beamery retrieving Greenhouse jobs using the Greenhouse Harvest API - Get Jobs. The storing of Greenhouse Jobs ID enables Beamery to either create a new vacancy or update an existing one.

Data Mapping Table

This table below shows the data mapping between Beamery and Greenhouse for Vacancies.

Beamery			Greenhouse			Notes
Field Name	Field Reference	Type	Field Name	Field Reference	Type
If a Requisition ID exists in GH then format: ‘Requisition ID-Job ID’. Otherwise format: Requisition ID (beamery generated)	If a Requisition ID exists in GH then format: ‘Requisition ID-Job ID’. Otherwise format: Requisition ID (beamery generated)	string	Requisition ID	requisition_id	string	Beamery Auto-generates a Requisition ID if it does not receive a Req ID from GH. Only the Auto-generated Req ID will show on the vacancy in beamery and the Job Id from GH is stored on the back end. Otherwise, if there is a Req ID from GH, this is concatenated with the Job ID from GH and this shows on the vacancy in beamery.
If a Requisition ID exists in GH then format: ‘Requisition ID-Job ID’. Otherwise format: Requisition ID (beamery generated). Job Id is stored in the backend	If a Requisition ID exists in GH then format: ‘Requisition ID-Job ID'. Otherwise format: Requisition ID (beamery generated). Job Id is stored in the backend	string	Job ID	id	string	Beamery Auto-generates a Requisition ID if it does not receive a Req ID from GH. Only the Auto-generated Req ID will show on the vacancy in beamery and the Job Id from GH is stored on the back end, and the job id cannot be used to search for the vacancy. Otherwise, if there is a Req ID from GH, this is concatenated with the Job ID from GH and this shows on the vacancy in beamery, and the job id can be used to search for the vacancy
Title (required)	vacancy_title	string	Internal Job Name	internal_name	string
Department	department	string	Department	department	string
Managed By	manager	string	Hiring Manager	hiring_managers > name	string
Sourced By	sourcer	string	Sourcer	sourcers > name	string
Description	vacancy_description	text	Job Notes	notes	text
Location	location	string	Office	offices	string
Privacy	visibility	enum	Confidential	confidential	boolean	There is no way anymore in GH to create a confidential vacancy
Salary	salary	string	Salary (custom field)	salary	string	Can be type number or short text in Greenhouse
Stages	stage	array	Job Stages	job
Status	status	enum	Status	status	string	Can be ‘Open’, ‘Closed’, or ‘Draft’

Beamery Vacancy Stages vs Greenhouse Vacancy Stages

NOTE: All vacancies manually created in Beamery will have the set of stages which are configured in Settings. Greenhouse jobs coming from the ATS integration do not have the same set of stages for all vacancies. Beamery displays the set of stages for each vacancy that were setup in GH. GH stages can be filtered via People Grid filter > vacancy stages, and Recipes > Filters i.e Automation. But Greenhouse stages are not visible in Settings. This limits the ability to use Filter Vacancy Stage IS/IS NOT throughout some parts of the product, including Pools & campaigns.

In Greenhouse Hired and Rejected are 'flags' and not stages. Beamery does not have flags and therefore flags are not mapped in Beamery. Candidates cannot be recognised as hired or rejected. However, rejected candidates are easily identified with a rejection reason, which is a field on the application in Beamery.

Vacancy by Department

Beamery allows you to sort by GH departments. Just click on the Vacancy Group in the Vacancies Tab.

Vacancy Owner

The vacancy owner in Beamery is not pulled in from Greenhouse and will default to the first user in the User list on the Beamery side.

Contacts / Candidates Object

Contacts are synced bi-directionally between Beamery and Greenhouse.

Beamery to Greenhouse
Contacts created in Beamery are not exported to Greenhouse by default. This is expected, as newly sourced talent may not be ready or qualified to apply for jobs. There are four ways for contact data to be synced to Greenhouse. The push is done by Beamery using Greenhouse API Post Candidate and Patch Candidate.

1. You can trigger a contact to be pushed to Greenhouse by clicking on the ‘Add To Greenhouse’ button on the profile.

2. You can select multiple contacts and bulk Add to Greenhouse

3. You can configure when contacts should be pushed to Greenhouse depending on your process using Beamery's Automation. For example, 'if a contact is added to a vacancy, then add to Greenhouse.'

4. Once a contact exists in both systems (contact in Beamery will have a Greenhouse ID and URL which are hidden), subsequent updates made to the contact in Beamery will automatically sync to Greenhouse.

Greenhouse to Beamery

Prospects and candidates created and updated in Greenhouse are imported to Beamery. Beamery gets notified by Greenhouse using Webhooks when a contact is created or updated. (Note that not all updates create a Webhook notification such as bulk actions.) The Webhook notification includes all data for Beamery to create or update contacts. The integration also identifies existing contacts in Beamery when a Greenhouse contact with the same email is imported. The Beamery contact is updated with the new data from Greenhouse. However, if there are duplicates in Greenhouse with the same email, these contacts are not auto-merged in Beamery to avoid loss of data in Beamery. (The integration supports bi-directional contact merges when you merge them yourself).

Merging: Greenhouse - Beamery Diagram Overview

Screenshot 2024-01-24 at 11.47.12.png

Below is a set of screenshots to show what merging candidates in Greenhouse looks like:

Benefits of enabling Auto-Merge by Email in Greenhouse

Both Beamery and Greenhouse are able to identify an existing contact in a similar fashion. For example, you can enable auto merge in Greenhouse Settings (as seen in the screenshot above), so when a candidate applies to another job using the same email, the existing contact is updated in Greenhouse with the new information.

However, auto merging contacts through the above methods can cause one system to have more contacts than the other, which would impact the data being synced correctly. For example, if Beamery would auto-merges two contacts, Greenhouse would still have the duplicates with different vacancies attached. Since Greenhouse is the source of truth, an update on one duplicate would overwrite the contact in Beamery. As a result, in Beamery the contact will only have the vacancies of one of the duplicate contacts, but not both.

The integration does not support auto merging when Greenhouse duplicates with the same email (but different Greenhouse ID’s) are imported to Beamery. However, the integration auto merges contacts when there is a Beamery contact not yet pushed to Greenhouse (i.e. they do not have a Greenhouse ID) and a Greenhouse contact with same email is imported.

Note: Beamery recommends you enable auto merge in Greenhouse to avoid the creation of many duplicates in both systems.

Merge Duplicates

The integration supports bi-directional sync when you merge contacts in Greenhouse or Beamery. When you merge duplicates with Greenhouse ID in Beamery, then the duplicates will also be merged in Greenhouse and vice versa.

Block Private Contacts

It is possible to block Greenhouse contacts that are marked as private from being created in Beamery. This can be set by Beamery if requested. However, due to the nature of only being able to mark a contact in Greenhouse as private after they have been created initially, means the contact will still flow through to beamery but any updates thereafter will be blocked. The only time a complete block of a private contact occurs, is if they were marked as private and existed in Greenhouse before the integration was switched on; In that case, the contact would not sync over to beamery when the historic sync is ran.

GDPR - Anonymize Contacts

To be compliant with GDPR, Beamery will support anonymization of contact data when candidates opt out. Once a contact is anonymized in Beamery, contact information is deleted and any updates from the ATS are blocked.

Greenhouse has similar consent and anonymization features, and the Beamery-Greenhouse integration supports two-way anonymization. The integration also supports two different configurations.

Bi-directional anonymization

If your recruitment workflows require anonymization to be enabled in both systems, then the integration allows bi-directional anonymization. Anonymizing a contact in Beamery will anonymize contact in Greenhouse and vice versa2

Greenhouse to Beamery anonymization

If your recruitment workflows requires Greenhouse to be the source of truth for all anonymization, the integration can be configured so Greenhouse is used to anonymize contacts in both systems, if the contact exists in both systems. Users but they can still anonymize a Greenhouse contact in Beamery, but that will not anonymize the same contact in Greenhouse through the integration.

Note: that Greenhouse allows anonymised contacts to be re-added, while Beamery does not allow this until candidate’s consent is received. Contacts that have been re-added in Greenhouse will NOT be added to Beamery until consent is received.

Topic	Beamery	Greenhouse
What data is removed?	All data is deleted except First/Last Name, Email and Social URLs, which are hidden from users' view. These prevent anonymized contacts from being accidentally added back into Beamery.	You can configure what data to be deleted.
How is anonymized contact different to a standard contact?	Anonymized contacts are not visible nor editable. Any updates from Greenhouse are also blocked. If however, a duplicate is created in Greenhouse, a new contact is also created in Beamery.	Anonymized contacts are not different to standard contacts. User can view and update contacts that were anonymized.
How to un-anonymize a contact?	Users can provide consent link to the candidates if requested or Super Admin can directly un-anonymize the contact.	There is no un-anonymization required. User can simply update the contact. Updates do not synchronize to Beamery, if contact is anonymized in Beamery.

Contact Data Mapping

Beamery			Greenhouse			Greenhouse to Beamery	Beamery to Greenhouse	Notes
Field Name	Field Reference	Type	Field Name	Field Reference	Type	API	API
Integration > Greenhouse > ID (required)	integration>greenhouse>id	string	Candidate ID	Candidate_ID	string
View in ATS URL (required)	integration>greenhouse>url	string	Beamery autogenerates the Greenhouse URL		-
First Name (required)	firstName	string	First Name	First_Name	string
Last Name (required)	lastName	string	Last Name	Last_Name	string
Email (required)	emails	array	Email Address	Email_Address	string
Attachment	attachment		Attachments	attachments	array
Consent Status	consentStatus	boolean	Custom Field	custom_field	enum
Global Tag	globalTag	array	Tags	tags	array
Phone	phoneNumbers	array	Phone Number	phone_number	string
Last Consent Date	lastConsentDate	date	Custom Field	custom_field	text
Links	links	array	Website, Social Media	website_addresses, social_media_addresses	string
Location>Address	address	string	Address	address	string
Location>Country	country	string	-	-	string
Location>Post Code	postCode	string	-	-	-
Notes	notes	object	-	-				The sync of Notes from Greenhouse to Beamery does not happen instantly, but usually occurs when other updates are made. The integration automatically keeps all notes as private when syncing from Greenhouse to Beamery. The sync of Notes from Beamery to Greenhouse happens instantly and Public notes sync over as public, and private notes sync over as private.
Primary Role	title	string	Title	title	string
Primary Company	company	string	Company	company	string
Profile Tags	tags	array	Tags	tags	array
Source	source	enum	-	-		Only on contact creation
Vacancy Integration ID that the contact applied to	vacancyId	string	Job Requisition ID	vacancyId	string
Vacancy Stage (required) associated to the vacancies the contact applied to	stageName	enum	Workflow Step	stageName	string
Rejection Reason associated to the vacancies the contact applied to	rejectionReason	string	Rejection Reason	rejection_reason	string
GH > Candidate / Referral - (set to the user)	N/A	-	Credited To	credited_to	string

Attachments

You can upload CV / resumes and other attachments to a prospect or candidate in Greenhouse. By default, CV / Resumes and Cover Letters are imported to Beamery, whereas other attachments are not.

Greenhouse does not notify Beamery when a new CV / Resume or Cover Letter is uploaded. However, when any other profile data is updated, the new files are imported to Beamery.

Confidential Candidates

Beamery imports all contacts that are made available from the import. Currently, the integration maps confidential Greenhouse contacts as public Beamery contacts. However you can request that confidential Greenhouse contacts are blocked from being imported to Beamery.

Creation Source

In Beamery, the Creation Source of a contact allows you to identify how the contact was created for example 'Manual' (contact created via the App) or 'CSV Import'. For contacts created from Greenhouse, the creation source is set to Greenhouse. This allows you to filter for any contacts created from Greenhouse or use an Automation Recipe (e.g. check contacts with creation source = Greenhouse, then add Global Tag).

Note: This is different from source, which identifies how the contact is known to the company e.g. LinkedIn or Event.

Custom Field Mapping using Tags

There are two field types that exist in Greenhouse which are not currently available to map via integration when synchronizing data from Greenhouse.

Credit to – When pushing data from Beamery to Greenhouse, we map the Beamery 'assigned to' field to push into the Greenhouse credit to field. However, this credit to field is not available to synchronise from Greenhouse to Beamery. We import users into Beamery, but the credit to field is not imported into Beamery. A Greenhouse user will not see which users from Greenhouse are assigned to vacancies and contacts in Beamery. This is because this data is not available via integration, and because not every Greenhouse user is in Beamery, we cannot map this. We recommend that prior to connecting data, or just after, users are added as a tag to contacts in Greenhouse. This allows us to import that data as a keyword/tag in Beamery, and then apply a bulk assign in Beamery.
Custom fields – Customers can create certain custom fields in Beamery and Greenhouse. These will not automatically map via integration
Bulk tags – the one key action that does not immediately get imported to Beamery from Greenhouse is a bulk add tag in Greenhouse (since Greenhouse do not currently support Webhooks for bulk actions). By adding individual tag synchronization to Beamery, if a contact is updated through another mechanism (for example, their stage is changed), the bulk added tag will then synchronise.

Users, Source, Departments

To ensure that prospects and candidates are synchronized accurately, the following data is synchronized from Greenhouse to Beamery every 1 hr.

Users
Source
Departments

Note: The synchronization process takes around 1 hour from Greenhouse to Beamery.

If a user exists in Beamery but not Greenhouse, or doesn't have a matching email between Greenhouse and Beamery, they will see an error alert that says "please check with support" etc. It is possible that this error can temporarily show up even if emails match in both systems, as for certain users this data is not immediately available via integration.

Beamery's Features for Integration Data

Feature	Supported	Notes
Contact Data Enrichment		One of Beamery's features is Enrichment via PDL [previously, Sherlock], whereby contacts are automatically enriched with publicly available information if detected by Beamery's search engine. This also applies to contacts created from Greenhouse. Enrichment is actioned via a contacts email or social link Enrichment is customisable It can be turned-off/on for contacts created in beamery It can be turned-off/on for contacts ingested via Greenhouse Note: Depending on the mapping, not all enriched data is exported from Beamery to Greenhouse.
Contact Enrichment from Attachments		Beamery enriches contact data from attachments and makes the content searchable. The integration currently does not support this feature for attachments imported from Greenhouse.
Search contacts Attachments by filename		Greenhouse & Beamery contact's attachments *cannot* be searched in Beamery by File Name
Search contacts Attachments by content		Greenhouse & Beamery contacts attachments can be searched in Beamery via Quick & Boolean Search by the files context i.e. attachment text search
Leaderboard Reporting		Beamery Leaderboard Reporting will be available for stages imported from Greenhouse.
Vacancy Stages Reporting		Beamery Reporting currently supports SINGLE hiring process flow where all vacancies share the same vacancy stages. Hence, Beamery Reporting does not currently support Vacancy Stages from Greenhouse.

How to setup the Integration

Please use the following guide for setting up the integration -

How to Integrate Greenhouse with Beamery