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:

  • Fully 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:


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 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.

  • 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.


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 on the 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 until field: 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 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 ($)

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

  1. Navigate to the Web Hooks page in the Greenhouse Dev Center

  2. 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

  1. On the same Webhooks page, you will create a second webook following the exact same process

  2. 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

  1. On the same Webhooks page, you will create a third webook following the exact same process

  2. 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 users 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:

  1. 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. And 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 note 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

Did this answer your question?