Connect to Greenhouse

Overview

This guide will walk you through establishing a connection required for the Greenhouse integration. It is divided into five sections.

• Before You Connect
• Customer Obtains API Key
• Establish Connection
• Clone Workflow
• Web Hook Setup in Greenhouse

Section 1: Before You Connect

Preconditions

• The Greenhouse connection requires authentication with an API Key in Greenhouse. You must be a Greenhouse Site Admin with the Developer Permissions listed below to set up the connection. 

  • • Manage ALL organization's API Credentials

    • Manage and configure web hooks

To view or add developer permissions to a Greenhouse user, navigate to the Users configure page (Configure icon > Users), select user, and navigate to the Permissions panel. Check the boxes for the Developer Permissions listed above.

For instructions on how to obtain an API Key, see Section 2 of this article or Manage Harvest API Key Permissions. 

Section 2: Customer Obtains API Key

• Step 1: Log in to Greenhouse. 
• Step 2: Click the gear icon at the top right of your screen.

• Step 3: Click Dev Center from the sub menu on the left of your screen.

• Step 4: Select API Credential Management.

• Step 5: Click the Create New API Key button at the top right of your screen.

• Step 6: The Create New Credential pop-up window will appear. Enter the following information in the fields shown below. Then, click the Manage Permissions button:
  • • API Type: Harvest (select this from the drop-down menu)
    • Partner (if applicable): (leave this blank)
    • Description: Paylocity Integration

• Step 7: The API Key Successfully Created pop-up window will appear. Click the Copy button. Store the key somewhere safe to use in Section 3. Then, click the I have stored the API Key button. 
  • Note: If you do not copy and store your API Key in a safe place, you will need to create a new API Key.

• Step 8: You will be taken to the Harvest API screen. Make the following selections. (Note: to expand each section, click the arrow located on the left side of each section.)
  • Applications:
    • Post: Hire Application
  • Candidates:
    • Get: Retrieve Candidate
    • Get: List Candidates

• Step 9: Click the Save button located at the bottom right of your screen. 

Section 3: Establish Connection

Task 1: Paylocity Representative Generates Link

This Task will be completed by a representative from Paylocity while on a call with the Early Access customer. The steps in this section will need to be completed separately for each Greenhouse company/application. 

• Step 1: On the left menu, click/expand Integration Management.

• Step 2: Click Apps from the drop-down menu.

• Step 3: Scroll down until you see each Greenhouse application. Click the application icon or anywhere within the row where the Greenhouse application is located.

• Step 4: You will be taken to the Greenhouse screen. Click the App Options button on the top right of your screen.

• Step 5: Select Generate Link from the drop-down menu.

• Step 6: A link will appear under the App Options button. Copy the link by highlighting the text, right clicking, and selecting Copy.

• Step 7: At this point, Paylocity will provide the link to the customer while on the call. 

Task 2: Early Access Customer Connects to Greenhouse

This Task will be completed by the Early Access customer while still on the call with their Paylocity representative. The steps in this section will need to be completed separately for each Greenhouse company/application. 

• Step 1: Paste the link into your browser. It will take you to the Connect Paylocity to Greenhouse screen. Enter the API Key. Then, click the Update App button. 

• Step 2: Inform your Paylocity representative once you have completed the connection steps. You will see a screen with a green checkmark. This indicates that the API Key has been stored.

Task 3: Paylocity Tech Services Confirms Connection in Cloudsnap

This Task will be completed by a representative from Paylocity while on the call with the Customer. 

• Step 1: After the Customer confirms that their credentials have been stored (Task 2), click the Test Connection button in Cloudsnap at the top right of your screen. If you are no longer on the Greenhouse page in Cloudsnap, follow Steps 1-3 in Task 1 of this section. 
  • If successful, a green checkmark will appear to the left of the Test Connection button. 
    • If the connection succeeds, this indicates that the Greenhouse connection has been established, and the connection can be used for Greenhouse workflows.
    • If the connection fails, check and correct the Greenhouse credentials.

• Important Note: If multiple companies should be connected to a single Paylocity Company ID, it is important to immediately move to Section 4 in order to name the recently connected Greenhouse app before connecting another Greenhouse app. Do not connect multiple Greenhouse apps without completing Section 4 after each connection. 

Section 4: Clone Workflow

This Task will be completed by a representative from Paylocity while on a call with the Early Access customer. The steps in this section will need to be completed separately for each Greenhouse company/application. 

• Step 1: On the left menu, click/expand Integration Management.

• Step 2: Select Workflows from the drop-down menu.

• Step 3: On the next screen, click Workflow Templates located on sub menu at the top of your screen. 

• Step 4: Click the Clone button to the right of the workflow titled Employees [New Hires] Greenhouse [Harvest] >> Paylocity Onboarding.

• Step 5: Go back to the main menu, and select Workflows.

• Step 6: Click My Workflows located on the sub menu at the top of your screen. 

• Step 7: Click the workflow titled Employees [New Hires] Greenhouse [Harvest] >> Paylocity Onboarding.

• Step 8: On the next screen, select the Webhook text to the right of the purple flag located at the top left of your screen.

• Step 9: In the center of your screen, the Trigger Configuration will appear. Select Webhook as the Trigger Type. Then, select and copy the full URL to the right of the text that says, "Post payload to". (Note: Make sure to paste this somewhere safe, because this URL will be used in the next section, and you will send it to the customer via secure mail later in this section.)

• Step 10: Click the Enable Basic Authentication button.

• Step 11:  Copy the Username and Password that appear under the Disable Basic Authentication button. (Note: Make sure to paste these values somewhere safe, because this URL will be used in the next section, and you will send it to the customer via secure mail on the next step.)

• Step 12: Send the URL (from Step 9) and the Username and Password (from Step 11) to the customer via secure mail. 

Section 5: Web Hook Setup in Greenhouse 

• Step 1: Log in to Greenhouse. 
• Step 2: To open Settings, click the gear icon located at the top right of your screen.

• Step 3: Click Dev Center located on the left menu.

• Step 4: Scroll until you see the Web Hooks option, then select it by clicking the Web Hooks link. 

• Step 5: You will be taken to another screen in the Dev Center. Select Web Hooks again.

• Step 6: Enter the following values in the Create a New Web Hook form. After filling out the five values below, click the Advanced Settings link. 
  • Name this web hook: Paylocity Integration
  • When: Candidate has been hired (select from the drop-down menu)
  • Endpoint URL: Enter the value obtained in Section 4, Step 9.
  • Secret Key: Enter your Paylocity Company ID.
  • Error Recipient Email: Enter the email that should receive any errors. 

• Step 7: The Advanced Settings options will appear. Enter the following values. Then, click the Create Web Hook option. 
  • Username: Enter the username obtained in Section 4, Step 11.
  • Password: Enter the password obtained in Section 4, Step 11. 
  • Disabled: No 

• Step 8: If successful, you will see a message at the top of your screen that says "Web hook created successfully". If you receive a 401 error, this indicates that the values are incorrect, so you will need to double check the values and complete the form again. 

Section 6: Name Greenhouse Applications

• Step 1: Click the vertical ellipsis to the right of the recently added Greenhouse application that has the green check mark and has not yet been renamed. 
  • Note: Once the Greenhouse app is connected, the connection will be indicated by a green check mark. If the customer has multiple Greenhouse apps/companies, it is important to name each app as soon as it is connected in order to avoid confusion about which Greenhouse apps correspond to the Greenhouse companies.
    • The first Greenhouse app has already been renamed ("Greenhouse- Test Company - 123456") and connected (indicated by the green check mark).
    • The second Greenhouse app was recently connected (indicated by the green check mark), but has not yet been renamed. 
    • The third Greenhouse app has not yet been connected nor renamed. 

• Step 2: ClickSettingsfrom the drop-down menu that appears.

• Step 3: You will be taken to the Edit App screen. In the first field (Name), name the Greenhouse application according to the naming convention below.
  • “Greenhouse” - <Company> - <Company ID>
  • Example:
    • Company: Test Company
    • Company ID: 123456
    • Greenhouse Application Name: Greenhouse- Test Company – 123456

• Step 4: In the Env field, select the Production environment from the drop-down menu.

• Step 5: Click the Submit button at the bottom right of your screen.

• Step 6: If the customer has multiple Greenhouse companies, repeat for each company.