Greenhouse Partner Integration API

​

Overview

​

Partnership Requirements

1

Apply to the Greenhouse Integration Partner Program

Visit the Greenhouse Integration Partner application page and begin the partner application process.

2

Select Integration Types

On the application form, select Assessment API, Webhook, and Harvest API as your integration types.
When you select Assessment API, you will be prompted to provide specific API endpoint URLs (see the screenshot attached with the next step).

3

Provide StackOne Endpoint URLs in the form

list_tests

Copy

Ask AI

https://api.stackone.com/external-trigger/greenhouse/list_tests?tenant-id=YOUR_GREENHOUSE_TENANT_ID

send_test

Copy

Ask AI

https://api.stackone.com/external-trigger/greenhouse/send_test?tenant-id=YOUR_GREENHOUSE_TENANT_ID

test_status

Copy

Ask AI

https://api.stackone.com/external-trigger/greenhouse/test_status?tenant-id=YOUR_GREENHOUSE_TENANT_ID

response_error

Copy

Ask AI

https://api.stackone.com/external-trigger/greenhouse/response_error?tenant-id=YOUR_GREENHOUSE_TENANT_ID

About the Tenant ID: The tenant-id parameter in these URLs should be replaced with a unique identifier of your choice. This ID is not provided by Greenhouse and is not generated by StackOne. You can use any unique value (e.g., your company name such as example-inc or acme-corp). This parameter is used by Greenhouse to create uniquely routed endpoints and distinguish between different integrations. Choose a value that makes sense for your organisation and use it consistently across all endpoints.

Greenhouse reviews applications on the first Monday of every month. A member of their Partnerships team will contact you with next steps.

4

Receive Partnership Credentials

Once approved, Greenhouse will provide you with:

• Partner Username
• Partner Password
• Any additional credentials needed

Use these credentials to complete the StackOne Configuration.

To test your integration app through your Greenhouse Sandbox, please contact Greenhouse Support and provide the External Trigger Token to enable the integration.

To obtain the External Trigger Token, please follow these steps:

• StackOne Configuration
• ATS User Enablement

​

Provider Side Setup

​

StackOne Configuration

1

Navigate to enable the Greenhouse at StackOne

Go to the ATS category on the Integrations page and enable Greenhouse.

2

Enable and Configure Greenhouse in StackOne

Fill out the necessary fields in the Greenhouse - Configuration modal:

• Authentication Type - Select Public + Partner API or Partner API to integrate with Greenhouse (for Assessment/Background Check integration).
  Difference between Public API & Partner API

  • Public API: Access to the StackOne Unified APIs, excluding the Assessments and Background Checks Unified API and its features.
  • Partner API: Access to the Assessments and Background Checks Unified API and its features, but not other StackOne Unified APIs. This allows you to integrate your provider's partner app with StackOne.
  • Public + Partner API: Access to all StackOne Unified APIs, including the Assessments and Background Checks Unified API and its features.
  • If you select Public + Partner API, the hiring team’s data will be included in the webhook notification.
    
  • If you select Partner API, the hiring team’s data will not be included in the webhook notification.
• Partner Category - Select the appropriate category based on your integration’s classification as a partner for Greenhouse. e.g.: Assessments or Background Checks
• Package’s List Endpoint URL - Implement and provide an endpoint to StackOne that StackOne will use to retrieve the list of packages when the recruiter wants to send a test to a candidate. Implement the following POST endpoint:
  Copy

  Ask AI

  curl --location 'https://your-domain.com/<route-to-the-post-endpoint>' \
  --header 'Content-Type: application/json' \
  --header 'x-stackone-signature: string' \
  --header 'Authorization: Basic <base64encoded-api-key>' \
  --data '{
      "account_id": "456551489512493411",
      "provider": "greenhouse"
  }'
  

  The expected response of the POST endpoint (list of packages). Refer to:
  • List Assessments Packages
  • List Background Check Packages
  Enter the endpoint into the designated field:
  Copy

  Ask AI

  https://your-domain.com/<route-to-the-post-endpoint>
  

• Partner’s Username - You will receive the username from Greenhouse support as mentioned in the previous step.
• Partner’s Password - The password will also be provided by Greenhouse support as mentioned in the previous step.
• Package ID - If you do not have the Package’s List Endpoint URL, you can specify a particular package ID that will be visible to the recruiter when they wish to send the test to the candidate.

How is the Package's List Endpoint URL different from a Static Package ID?

The Package's List Endpoint URL allows StackOne to fetch a list of available packages from your system, while the Static Package ID is fixed and available for users to select on the provider's side.

When you have a Package's List Endpoint URL
A list of packages will be available to select in Greenhouse.

When you have a Static Package ID
A static package ID will be available to select in Greenhouse.

At least one field is necessary for making packages available in the Provider's UI. Preference will be given to the Package's List Endpoint URL, even if both fields are configured.

Click on the Confirm or Save Changes button to enable Greenhouse, which allows end-users to link their accounts via the StackOne Connector Hub.

3

Add a Webhook

Navigate to the Webhooks page, click on Add webhook and fill out the form:

• Name: Enter your webhook with a recognisable name.
• URL: Enter the URL where the webhook will send the notification of the enabled events.

Enable webhook events from the Events tab for Assessment & Background Check, such as Assessments Order & Background Check Order.

Click the Confirm and Save buttons to add the webhook.

​

ATS User Enablement

​

ATS User Experience

​

Send the test to the candidate from Greenhouse

​

User will see after test has been sent

​

ATS User Experience Customisation

1

To Update the result via unified api

Utilise the following endpoints to update the results:

• Assessment Update Result
• Background Check Update Result

Utilise the following endpoint to get metadata to update the result of the assessment or background check:

• Connector Meta Information with the provider key greenhouse for model assessments/results.update or background_checks/results.update

Fields (when provided)	User sees in Greenhouse
Result URL	Visible as a View Report link in the Grading Instructions tab under Go to Interview Kit, and as a Go to Test link.

2

How will the results of the assessment/background check be displayed to the user in Greenhouse?

When a user opens a candidate’s application, they will see the updated score along with its application stage.

Click the Go to Interview Kit link to access more detailed test results.

By default, the test result status will be sent as complete. Multiple updates are not allowed for a test.

​

Testing Checklist

• Once the integration is published by Greenhouse, it is visible in the Greenhouse Marketplace/Partner Directory under Assessments or Background Checks categories.

• Selected Public + Partner API or Partner API
• Package’s List Endpoint URL is correct.
• Valid Partner’s Username and Password
• Package’s List Endpoint response is expected according to the following endpoint’s response:
  • List Assessments Packages
  • List Background Check Packages

• Shared the External Trigger Token to the Greenhouse support, and they have enabled the partner integration app for your Greenhouse account.
• Once the app is enabled by Greenhouse for the user, the integration is visible to add as a stage in Jobs > Interview Plan under the specific Job.

• Added a webhook for Greenhouse and enable it with the events such as: Assessment Order or Background Check Order
• Valid webhook URL to receive assessment/background check notifications.

• Navigate to specific Job > Interview Plan > Add Stage > Select enabled Integration app as a stage that will be visible under the candidate application.
• If you’ve configured Package’s List Endpoint URL, a list of packages is visible in the dropdown field when you click the Send test to candidate link.
• If you’ve configured Static Package ID, a single package is visible in the dropdown field when you click the Send test to candidate link.
• Select a package, click Send Test, and send the webhook. A message Submitted tests will appear if the notification has been sent.

• Success response from the update result endpoint.
• Updated result details to Greenhouse’s UI.

​

Troubleshooting