Greenhouse Recruiting’s integration with Agora allows companies to seamlessly fit the creation of Agora’s interactive Offer Letters into their current offer workflow:
- Fully create the Agora Offer Letter in Greenhouse without needing to log in to the Agora app (with some exceptions, outlined below).
- The unique Agora Offer Letter URL is then pushed back into a custom field in Greenhouse immediately after creation.
You can preview an example of an Agora Offer Letter here.
Agora uses the Harvest API and webhooks, with limited permissions, to send a candidate’s unique Offer Letter URL back into a custom field in the Greenhouse Recruiting offer. This streamlined workflow creates your interactive Agora Offer Letters based on the creation (and subsequent updates) of offers in Greenhouse Recruiting.
Other than sending the Agora Offer Letter URL back to Greenhouse Recruiting, this is a one-way integration. Offer Letters created in Agora won't be sent back to Greenhouse Recruiting.
In addition to any user permissions in Greenhouse Recruiting, you'll need to be an Owner or have Company Settings permissions enabled in Agora.
Create a Harvest API key for the Agora integration
To configure the Greenhouse Recruiting / Agora integration, you’ll need to create a Harvest API key.
Follow the steps in this article to create the key, and verify that the permissions below are selected when configuring the Agora Integration.
Credentials
In the Create New Credential box, make the following selections:
- API Type: Harvest
- Partner: Agora (optional)
- Description: Agora Harvest API Key
Permissions
Verify that all the following permissions are selected for the Agora integration:
- Applications
- Select all
- Candidates
- Select all
- Users
- Select all
- Offers
- Select all
- Jobs
- Select all
- Custom fields
- Select all
- Custom field options
- Select all
Complete setup in Agora
Step 1: Navigate to Agora setup
After generating the API key in Greenhouse Recruiting, log in to Agora and click Settings on the left navigation panel.
Click ATS under the Integrations menu and click Connect under the Greenhouse tile.
Click Connect Greenhouse.
Step 2: Enter Harvest API Key in Agora
Follow the prompts on the setup screen, entering your API key credentials in Step 2 of the process.
Step 3: Create an integration user in Greenhouse Recruiting to update the offer links
In order for Agora to update Greenhouse Recruiting with the candidate’s offer link, you'll have to create a user account in Greenhouse Recruiting.
This user won't be associated with a real person at your organization but is an automated integration user that will update the candidate's offers when they're sent from Agora.
When creating the integration user, use the email from Step 3 of the Agora setup.
Your integration user will need to be a Site Admin with the user permission Can see private notes, salary info, and manage offers.
When you're finished, save the new user.
After the integration user is complete, you'll need to retrieve the UserID. Navigate to the Users page in Greenhouse Recruiting and open the integration user's profile. The user's ID will be located in the URL at the top of the page.
Copy the numbers from the URL and paste them in Step 3 of the Agora setup.
Enter the values in the Agora setup.
Click Next.
Step 4: Mapping your variables
To ensure the integration functions correctly, you'll need to map the Agora Offer Letter fields to the Greenhouse Recruiting Offer Fields used by your organization.
This mapping ensures that all the required fields will be populated in Agora and your offer letter details are consistent between Greenhouse Recruiting and Agora.
To map a field, you'll need to select the Greenhouse Recruiting offer field from the dropdown menu. Each field will list out all the offer fields that are created in Greenhouse Recruiting for your organization.
Since you've completed the basic setup, Agora will be able to see your existing Offer Fields in Greenhouse Recruiting and suggest mappings to the required Agora fields. However, review the suggested fields to ensure the information is accurate. If needed, select a new field from the dropdown menu.
Note
You'll need to define field mappings for the following fields in Agora:
- Base salary
- Candidate email
- Candidate first name
- Candidate last name
- Equity type
- Job Title
- Quantity of shares
- Offer Letter URL
- Offer Valid until
Importantly, these fields are required for mapping, but may not be required to create an offer. For example, if a candidate won't receive an equity grant as part of their compensation package, the field will be left blank when creating an offer in Greenhouse Recruiting. However, it's required that these fields be mapped during the integration setup to ensure that this information is correctly exchanged between the two applications when it is created.
The following fields are always required to create an offer in Agora:
- Base salary
- Candidate email
- Candidate first name
- Candidate last name
- Job title.
Other Available Fields
Outside of the required Offer Letter fields listed above, there are nine other fields available on Agora's Offer Letters that can map if they are relevant to your organization:
- Candidate address
- Location
- Manager name
- Manager title
- Sign-on bonus
- Start date
- Target bonus ($)
- Target bonus (%)
- Target Commission ($)
Step 5: Define Offer Letter URL field
When your offer is created, a unique URL for the candidate's Agora Offer Letter will be created and available both in Greenhouse Recruiting and the Agora app.
Agora will create a new custom field in your Greenhouse account for you called agora_url. To make sure that Agora can create a new field during this setup process, make sure there is a yellow information box next to the new field.
Create webhooks
Agora's integration relies on three webhooks to create, update, and delete offer letters. Webhooks are a way to send automated messages or information from one app to another, based on events or triggers. They are necessary for Agora to keep your offers up to date with Greenhouse.
Follow the steps in this article to create your webhooks. Use the values listed below to configure the webhooks. You'll need to create three webhooks for this integration.
Webhook 1: Offer Created
- Name: Agora [Offer Created]
- When: Offer Created
- Endpoint URL: The Endpoint URL provided by Agora
- Secret Key: The Secret Key provided by Agora
Webhook 2: Offer Updated
- Name: Agora [Offer Updated]
- When: Offer Updated
- Endpoint URL: The Endpoint URL provided by Agora
- Secret Key: The Secret Key provided by Agora
Webhook 3: Offer Deleted
- Name: Agora [Offer Deleted]
- When: Offer Deleted
- Endpoint URL: The Endpoint URL provided by Agora
- Secret Key: The Secret Key provided by Agora
Note: You can find the webhook information in step 5 of the Agora setup.
Use the Agora integration with Greenhouse Recruiting
Overall, the Agora integration follows the workflow below:
- An Agora Offer Letter is created when a new offer is created in Greenhouse Recruiting. This process adheres to any offer approval steps that may exist in Greenhouse Recruiting.
- Any time an offer is changed in Greenhouse, it will be immediately updated in Agora.
- Any changes to a candidate's offer status in Greenhouse Recruiting (for example, marking the candidate as hired or the offer as rejected) will update the Offer Letter Status in Agora.
- Offers deleted in Greenhouse Recruiting will also be deleted in Agora.
The Agora Assignee (the offer's owner) is determined based on an email address match between the users in Agora and the users in Greenhouse. It's a best practice to add all of the potential Assignees/offer creators into Agora prior to setting up the integration.
After you set up the Agora-Greenhouse integration, here's what will happen:
- Agora will begin importing your current and historical Greenhouse Recruiting offers into Agora
- After the import is complete, any Offer Letter URLs will be added to offers in Greenhouse Recruiting
Note: The Agora Assignee (the offer's owner) is based on a matching email address match between users in Agora and the users in Greenhouse Recruiting. Since it's not possible to link an Assignee (offer creator) to offers after they've been imported, add all of the assignees/offer creators into Agora prior to setting up the integration.
Only the individuals with the Owner permission group in Agora can add new users in Agora on the Admins tab.
Once the integration is set up, an Agora Offer Letter is automatically generated for every offer made in Greenhouse Recruiting.
Once an offer has been created, refresh the page or come back and click on Manage Offer on the candidate's record to pull up the offer. The candidate's unique Agora Offer Letter url will have automatically been populated into the Agora URL field.
In Agora, a Greenhouse logo will display on the Offers page when an offer is automatically created. Offers without that icon were manually created in Agora.
The Greenhouse icon will also display next to the candidate's name to indicate they are synced to Greenhouse Recruiting. An entry will also display in the Activity Log. Any changes made in Greenhouse Recruiting will be reflected on this page.
Testing the integration
Agora recommends creating a few test offer letters to ensure the integration is working properly.
After the setup is complete, navigate to the Offer Fields page within Greenhouse Recruiting and view the new agora_url field that has been created.
Some customers change the field name to "Agora URL (do not modify)" to avoid issues where recruiters would update the Agora URL
Additionally, if you want to include the offer link in your emails from Greenhouse Recruiting, check the Create new email token checkbox.
Note: Custom offer tokens can be used only in offer templates and in email templates created in the My Templates section. Custom offer tokens cannot be used in email templates created in the Organization-Wide Templates section. Read more here.
Additional resources
For additional information not covered here, reach out to hello@getagora.com or review additional articles in Agora’s Help Center.