Agora's offer letter creation integration with Greenhouse is unique in the fact that it allows you to seamlessly fit Agora into your current workflow:
Recruiters can create the Agora offer letter in Greenhouse without needing to log in to the app (with some exceptions, outlined below).
The unique Offer Letter url is pushed back into a custom field in Greenhouse immediately after creation.
Candidate's don't need to create an Agora account to view their offer letter.
All offer letters are saved within Agora (and accessible through Greenhouse) even after a candidate accepts the offer. This allows the candidate to reference back to what was included in their total comp and to continue to use the modeling tools.
This article covers:
Read about how the Greenhouse integration works or skip ahead to one of these sections:
Video overview of the Greenhouse integration
Steps for setting up the integration
Why can't I find the Offer Letter I created in Greenhouse in Agora?
How exactly does the integration work:
Agora uses a Harvest API and webhooks, with limited permissions, to push a candidate’s unique Offer Letter url back into a custom field in the Greenhouse offer. This allows for a streamlined workflow to create your interactive Agora Offer Letters based on the creation (and subsequent updates) of offers in Greenhouse.
An Agora Offer Letter will be created upon a new offer creation in Greenhouse (respecting any offer approval workflows that may be in place).
Continuously updated - any time an offer is changed in Greenhouse, it will be immediately updated in Agora.
Changes to a candidate's offer status in Greenhouse (i.e. when the candidate is marked as hired or the offer was rejected) will inform the Offer Letter status in Agora (Published, Accepted, Rejected). Offers deleted in Greenhouse will 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 designated Recruiter attached to the candidate's record in Greenhouse. It's a best practice to add all of the potential Assignees/offer creators into Agora prior to setting up the integration.
Note that outside of the ability to push the Agora Offer Letter URL into the custom field in Greenhouse, this is a one-way integration. Offer Letters created within Agora will not be pushed back to Greenhouse. See other limitations below.
Greenhouse Integration Overview Video
Setting up the Integration
In order to set up the Agora-Greenhouse integration, you will need to have Site Admin privileges within Greenhouse and be either an Owner or have Company Settings permissions enabled in Agora.
To get started, head to Agora and login. Then click on the Settings menu item on the left navigation.
2. Click ATS listed under the Integrations navigation item and then click the Connect button under Greenhouse.
3. Click Connect Greenhouse to get started.
Step 1: Prerequisite Permissions
Confirm your permissions. In order to proceed, check if you have the correct permissions in Greenhouse.
Make sure you are a Greenhouse site admin
Make sure you have the "Can manage ALL organization's API Credentials" permission to generate an API key
Make sure you have the "Manage and configure web hooks" permission to setup webhooks.
Step 2: Set up API Keys
In order for Agora to gain access to the data necessary from Greenhouse to generate offers, we need to create a Greenhouse API Key. To create one, carefully follow the steps outlined below:
I. Navigate to Greenhouse's Dev Center & API Credentials page
II. Click Create New API Key
III. Select Harvest For API Type, and enter Agora for the description
IV. Click Manage Permissions and click Copy. Then paste your API Key in the field in Agora.
First....
Then....
V. On the Greenhouse page, click I have stored the API key which will bring you to the page to manage the API key's permissions. You need to check these boxes to request the following permissions:
Applications
Candidates
Users
Offers
Jobs
Custom fields
Custom field options
Click Save on both pages and move on to the next step!
Step 3: Create a New Greenhouse User
In order for Agora to update Greenhouse with the candidate's offer link, you need to create an Agora user in Greenhouse following the steps below:
I. Navigate to Greenhouse's "Add New Users" page
II. Copy the pre-filled email in the Agora setup page and paste it in the "Enter Users Emails" field Greenhouse
In Agora:
In Greenhouse:
III. In the Set Permissions section of the page in Greenhouse, click Assign next to Site Admin and check the box next to:
Can see private notes, salary info, and manage offers
Then click Save to finish adding the new user.
IV. Now you will navigate to the Users configuration page in Greenhouse. Locate the newly created user (by the email address you entered) and click on that user.
On the user's page in Greenhouse, copy the user ID from the URL in your browser.
In Greenhouse:
Paste into Agora:
Click Next to move onto step four.
Step 4: Mapping your Variables
An important next step critical to the success of the integration is the mapping of Agora Offer Letter fields to the Greenhouse Offer Fields your organization uses. This allows for the details of your offer letters within Greenhouse to be mapped properly to the required and optional Offer Letter fields within Agora.
A few important notes:
Based on the integration you just enabled, Agora is able to view your existing Offer Fields in Greenhouse and will suggest mappings to the required Agora fields.
You must audit the suggested mappings to ensure the correct fields have been chosen.
The required Agora Offer Letter fields are:
Base salary
Candidate email
Candidate first name
Candidate last name
Equity type
Job Title
Quantity of shares
Offer Letter URL
Offer Valid until
Although these fields are required to be mapped, they are not all required to create an offer. For example, if a candidate doesn't have equity included as part of their compensation package, those fields can be left blank during offer letter creation in Greenhouse.
The minimum fields that are required to create an Agora Offer Letter are: Base salary, Candidate email, Candidate first name, Candidate Last name, and Job title.
Note regarding the
Offer valid untilfield: If no expiration date is provided in Greenhouse, the expiration date in Agora will default to two months after the start date or two months after the offer creation date (if no start date is provided).
If an expiration date is provided in Greenhouse, the offer will no longer be visible as of 10:59am GMT (2:59 am PST) that day. If you would like the offer letter to be visible for a longer period of time during that date, you may either update the time zone within the offer in Agora or set the expiration date to the next calendar day in Greenhouse. (i.e. if you would like the offer to be visible until the end of the day on January 10th, set the expiration date in Greenhouse to January 11th.)
Offers that have been marked as "Accepted" will continue to be visible after the expiration date.
Offer Letter URL field
Upon creation of your offer, the unique URL for the candidate's Agora Offer Letter will be created and available both in Greenhouse and the Agora app.
Within setup, you allow Agora to create a new custom field in your Greenhouse account for you called agora_url. You will know Agora is creating a new field when there is a yellow information box next to the proposed new field:
Other Available Fields:
Outside of the required Offer Letter fields (above), there are nine other default fields available within Agora's Offer Letters that you're able to map to if they are relevant compensation types for your organization. These include:
Candidate address
Location
Manager name
Manager title
Sign-on bonus
Start date
Target bonus ($)
Target bonus (%)
Target Commission ($)
In addition, any custom offer letter fields that have been created will appear as a mappable field when enabling the Greenhouse integration.
Mapping a Field:
To map an Agora field to a Greenhouse field, click in to the field to open a drop down that will display all of the fields available in your Offer Fields in Greenhouse. Select the correct field.
After you have completed the mapping exercise, click Next to proceed to the final step.
Step 5: Setting up 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.
Setup all three (3) webhooks below by following the steps carefully.
I. Offer Created
Navigate to the Web Hooks page in the Greenhouse Dev Center
Fill out the Webhook Form with the following information and click "Create Webhook"
Name this webhook: | [Agora] Offer Created |
When (dropdown select): | Offer Created |
Endpoint URL | Copy the unique URL from the Agora setup page and paste into Greenhouse |
Secret Key | Copy the unique Secret Key from the setup page and paste into Greenhouse |
Error Recipient Email | The email address (your's) that error notifications will be delivered to |
Disabled? | Select "No" |
In Agora:
In Greenhouse
II. Offer Updated
On the same Webhooks page, you will create a second webook following the exact same process
Fill out the Webhook Form with the following information and click "Create Webhook"
Name this webhook: | [Agora] Offer Updated |
When (dropdown select): | Offer Updated |
Endpoint URL | Copy the unique URL from the Agora setup page and paste into Greenhouse |
Secret Key | Copy the unique Secret Key from the setup page and paste into Greenhouse |
Error Recipient Email | The email address (your's) that error notifications will be delivered to |
Disabled? | Select "No" |
II. Offer Deleted
On the same Webhooks page, you will create a third webook following the exact same process
Fill out the Webhook Form with the following information and click "Create Webhook"
Name this webhook: | [Agora] Offer Deleted |
When (dropdown select): | Offer Deleted |
Endpoint URL | Copy the unique URL from the Agora setup page and paste into Greenhouse |
Secret Key | Copy the unique Secret Key from the setup page and paste into Greenhouse |
Error Recipient Email | The email address (your's) that error notifications will be delivered to |
Disabled? | Select "No" |
Finally, click Done in Agora and you've completed the setup!
What happens after setup?
After you set up the Agora-Greenhouse integration, here's a few next steps:
Agora will begin the process of importing all of your current and historical Greenhouse offers into the app and candidate Offer Letter urls will retroactively be added to offers in Greenhouse
It's important to note that the Agora Assignee (the offer's owner) is based on an email address match between the users in Agora and the Recruiter assigned to the candidate in Greenhouse. It's a best practice to add all of the assignees/offer creators into Agora prior to setting up the integration so Offer Letters are correctly linked to the right person from the beginning. It won't be possible to retroactively add an Assignee (offer creator) after the offers have been imported. Only individuals with the Owner permission group can add new users in Agora on the Admins tab.
We recommend creating a few test offers to ensure the integration is working properly.
After the set up is complete, you may want to navigate to the Offer Fields page within Greenhouse and view the new agora_url field that has been created. You may want to change the field name to say Agora URL (do not modify) so recruiters know to not change that field. You may also want to check the box next to "Create new email token" so it can be included in your Greenhouse email templates.
If you intend to insert the Agora URL email token into email templates, note this Greenhouse limitation. 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 in Greenhouse's Help Center article.
How to use the integration:
Once the integration is set up, an Agora Offer Letter is generated automatically for every offer made in Greenhouse without any changes to your workflow.
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.
Within Agora, you will see an indication on the Offers page when the Greenhouse icon appears. Offers without that icon were manually created in Agora.
Click on the candidate in the list to pull up their record.
On the candidate record, the Greenhouse icon shows up next to their name and within the activity log. Any changes made within Greenhouse will be reflected here.
Editing Offers
There are only three things that can be edited within Agora after an Offer Letter has been created in Greenhouse:
Add Greets to the candidate's Offer Letter. Learn more about Greets here!
2. Select a legal document template and co-signer. This only applies to companies who have set up Agora's Docusign Integration
3. Change the Benefits package from the default to another package. An Admin with Company Setting permissions can set up new Benefits packages here.
Limitations
With the exception of pushing the Agora Offer Letter URL into the Agora URL offer fields, the Agora/Greenhouse Integration is a one-way integration and will not write back to Greenhouse. Offer Letters created within Agora will not be pushed back to Greenhouse. However, if the Agora Docusign integration has been enabled, executed Docusign documents can be pushed back into Greenhouse.
You currently are unable to select the non-default benefits package within Greenhouse. If the candidate you are creating an offer for doesn't have the default benefits package, you will need to remove or change it within Agora.
You are unable to select the non-default vesting schedule if you have more than one created in Agora. Offers that require a non-default vesting schedule will need to be created manually. View your default vesting schedule in the Equity Options settings page in Agora
If you are using Agora's Docusign integration, you will need to log in to the Agora app to select the legal document template and co-signer you intend to use.
If you would like to include Greets in your offer letter you will need to log in to Agora to get the Greets URL to share with team members who wish to add Welcome messages to the letter.
You are not able to create flexible offers within Greenhouse. Flexible offers will need to be created within Agora. Learn more about Flexible Offers.
How to disable the integration:
1. Navigate to the Users page within Greenhouse, click on the Agora user that was added (will contain @getagora.com), and click on Disable User.
2. Navigate to the Webhooks page within Greenhouse, click on the X next to the three webhooks that start with [Agora].
3. Navigate to the API Credentials page within Greenhouse, hover over the Agora API key that was created and click the Revoke icon.
The integration can also be disabled from the Agora ATS integrations page. Click on the Greenhouse box and then click the Disconnect button
Troubleshooting
Why can't I find the Offer Letter I created in Greenhouse in Agora?
Here are some of the most common reasons recruiters have trouble finding their offers.
Greenhouse Sync Related Causes
Have your Greenhouse fields been mapped correctly? If you just set up Greenhouse and offers are not coming through at all, or coming through with missing information, it helps to take a second look at the Greenhouse setup page and ensure that your variables have been correctly mapped.
Has the offer been approved in Greenhouse? If your organization has an approvals process in place, the offer will not be available in Agora until the offer has been fully approved in Greenhouse
Is this the only offer failing to come through? It could be an offer specific issue - check that the offer has been approved and has all of the required information. It also can help to make a small change to an offer (i.e. the expiration date) and then immediately change it back. This triggers the webhook and can reset the offer (similar to doing a restart on your computer!)
What stage is the offer in within Greenhouse? If an offer is marked Accepted or Rejected in Greenhouse, it may not show up on the main Agora offers page depending on the which stage boxes have been checked. Offers that have been deleted in Greenhouse will no longer be accessible in Agora.
Permissions/User Related Causes:
When was the Recruiter invited to the Agora account? If the user was invited to the Agora account after the offer had already been created the Recruiter may not be able to see it if they have limited permissions to view offers. Although the offer will appear in Agora, we don't retroactively match new users with offers that have already been created.
Who is the Recruiter assigned to the candidate record in Greenhouse? Agora looks at the Recruiter listed on the candidate's record, not the individual who created the offer, if that person is different
Am I using the same email to login to Greenhouse and Agora? Agora relies on email address to determine the Assignee. Check that you are using the same email address as login credentials to both Agora and Greenhouse.