Documentation

Connect Greenhouse

Greenhouse takes three passes: create credentials in Greenhouse, paste them into Voyse, then add webhooks so a change in Greenhouse reaches Voyse the moment it happens rather than at the next day's import. The first two get your roles across; the third is worth doing the same afternoon.

Before you start

In Greenhouse you need permission to manage your organisation's API credentials, and permission to manage webhooks. Both sit with Greenhouse admins.

Greenhouse advises creating the credentials from an integration user account rather than your own — credentials tied to a person stop working when that person is deactivated.

Create the credentials in Greenhouse

  1. In Greenhouse, select the Configure icon on the navigation bar, then Dev Center, then API Credential Management.
  2. Select Create new API credentials.
  3. For API type, choose Harvest v3 (OAuth). Voyse works with that type and not the older one.
  4. Add a description you'll recognise later, such as Voyse.
  5. Grant the credentials read access to job posts, jobs, departments and offices, and write access to candidates, applications and attachments. Those cover importing roles and sending applications back.
  6. Add these as well if you want the optional features: prospect details, notes, job notes, users and custom fields. Each is what a Capabilities row below depends on.
  7. Copy the Client ID and Client secret. Greenhouse shows the secret once.

Connect it in Voyse

  1. Select Integrations in the sidebar.
  2. Under Connect an ATS, choose Greenhouse.
  3. Paste the Client ID and Client Secret, then select Connect.
  4. The pill by the provider's name reads Connected, and Sync status fills in once the first import finishes.

Add the webhooks

Without these, your roles still arrive — once a day, and whenever you select Sync now. With them, a role you publish in Greenhouse appears in Voyse within moments.

  1. On the Voyse Integrations page, copy the Webhook URL and the Secret key from the Webhooks section.
  2. In Greenhouse, go to Configure → Dev Center → Web hooks.
  3. Create one webhook per event, each with the same Endpoint URL and Secret Key you copied from Voyse. The events Voyse acts on are Job created, Job updated, Job deleted, Candidate has changed stage, Candidate has been hired and Application updated.
  4. Back in Voyse, Last webhook on the Integrations page changes from Never the first time one arrives.

Other Greenhouse events can be sent, but nothing in Voyse listens for them. Treat the secret key as a credential: it is what tells Voyse the message really came from your Greenhouse.

What comes across

Job posts that are live and external. An internal-only post, or one that isn't live, stays in Greenhouse. Departments and offices come across with them.

Capabilities lists what your credentials allow. Check capabilities re-tests them after you change permissions in Greenhouse.

Feature What it needs
Job Sync, Application Submit, Webhook Events Essential, and covered by the read and write access above
CRM Prospects Prospect details
Candidate Notes Notes
Job Notes Job notes and users — Voyse needs the user list to attribute the note to somebody
Custom Fields Custom fields
Hiring manager contacts Job hiring managers

Three settings worth filling in

Once Custom Fields is granted, two selectors appear under Capabilities, and a third appears with Job Notes:

  • Salary field — which Greenhouse custom field holds a role's salary. Create one in Greenhouse under Configure → Custom Options → Custom Fields with the type Currency Range, for jobs. If your organisation uses pay transparency, Voyse falls back to that when the field is empty.
  • Candidate intent score field — where Voyse writes high, medium or low when someone applies, reflecting how much they read and asked beforehand. Use a Short text custom field for candidates, so the value displays.
  • Job notes attribution — which Greenhouse user is shown as the author of the weekly note Voyse writes on each role. A service account is a fair choice.

All three save as you change them.

If it didn't work

  • Invalid Greenhouse credentials when you connect — the wrong API type. Harvest v3 (OAuth) credentials are a client ID and secret; the older type gives you a single key, which this form won't take.
  • Everything granted except one row — that row's permission is missing from the credentials. Add it in Greenhouse, then select Check capabilities.
  • Roles missing from Voyse that are open in Greenhouse — check the job post is live and not internal-only.

The rest of the page — sync status, the activity log, disconnecting — is covered in Connect your ATS.