This article explains how to set up the Greenhouse integration with Personio. When connected, the Greenhouse integration automatically creates a new employee profile in Personio when a candidate is marked as Hired in Greenhouse. The integration synchronizes specific attributes between Personio and Greenhouse, so Personio can import the corresponding information into your account.

Prerequisites for a successful integration

Before beginning the integration process, make sure the following is in place:

• You have an admin role or edit permissions via your employee role for Marketplace Integration and API.
• You have access to the Dev Center (Developer Permissions) in Greenhouse.
• Populate the attributes First name, Last name, and Email address in Greenhouse, as the integration needs these to exchange information successfully.

Connect Greenhouse

Set up the Greenhouse integration directly in Personio's Marketplace using the Configuration Wizard. Follow these steps:

1. Go to Marketplace in Personio. Search for and select the Greenhouse integration.
2. Click Connect to open the Configuration Wizard. 
3. Click Authenticate Greenhouse to begin.
4. On the Greenhouse authorization screen, enter your Greenhouse email and click Log in to Greenhouse.
5. On the second authorization screen, optionally select Authorize using a service account. This is a recommendation for production environments, as it creates an org-level connection that persists if your personal account changes.
6. Click Authorize to complete the connection and continue to the next step.

Authenticate Personio

In step two of the Configuration Wizard, you need to grant the Greenhouse integration access to the necessary Personio data. Follow these steps:

1. Review the permissions that the Greenhouse integration requires. Grant the integration Write employee data access. Personio needs this access to create employee profiles from hired candidates.
2. Click Next to continue to step three of the Configuration Wizard and map attributes.

Tip:
You can review the granted permissions after the setup process in the Greenhouse integration in Settings > Security & Integrations > API credentials.

Map attributes

In step three of the Configuration Wizard, you can select which Greenhouse attributes to synchronize with Personio. Follow these steps:

1. Review all the attributes and make sure each Personio attribute matches the corresponding Greenhouse attribute.
2. Click Add new attribute to include more attributes.
3. Click Next to continue to step four of the Configuration Wizard.

Note:
If you're mapping attributes of the type List of options, make sure the attribute values are identical in Personio and Greenhouse.

Important notes about attribute mapping

If the integration creates an employee profile but some attributes are missing, this might be due to mapping issues between Greenhouse and Personio. Consider the following common cases:

• Date attributes: Personio requires dates in the format DD.MM.YYYY. If you don't directly map a Personio date attribute to a Greenhouse date attribute, the data may not transfer correctly.
• Currency/salary attributes: Greenhouse combines the value and currency type into one field.  You cannot map these combined fields to Personio’s separate currency fields.
• Number-based attributes: Greenhouse multi-select attribute types are incompatible with Personio’s integer or decimal attributes and cannot be mapped.

Review your attribute mappings to make sure they're compatible and adjust as needed.

Create a webhook

In step four of the Configuration Wizard, you need to create a webhook in Greenhouse. Follow these steps:

1. In the Personio Configuration Wizard, copy the Endpoint URL. You need to enter this in Greenhouse in the next step.
2. In Greenhouse, go to Configure > Dev Center > Webhooks > Create A New Webhook.
3. Fill in the following fields:
   • Name: Enter a descriptive name for the webhook. We recommend "Personio integration".
   • When: Candidate has been hired.
   • Endpoint URL: Paste the URL copied from the Personio Configuration Wizard.
   • Secret Key: A unique key of your preference.
   • Associated Partner: Select Personio
   • Deactivated? Leave this set to Yes for now. Once you complete the remaining steps in Personio, you need to change this to activate the webhook. 
4. Click Create Webhook
5. Return to Personio and click Finish. 
6. Return to Greenhouse, find the webhook you created, and change Deactivated from Yes to No to activate it.