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 every permission under Required in the table below.
  6. Grant the Optional permissions for the features you want.
  7. Copy the Client ID and Client secret. Greenhouse shows the secret once.

Required

These cover importing roles and sending applications back.

Permission Access Why Voyse needs it
Job posts Read Imports your live, external job posts and their application questions
Jobs Read Gives each role its department, location and salary
Departments Read Names the department a role belongs to
Offices Read Names the location a role is based in
Candidates Read and write Creates a candidate when someone applies, and reads their name back later, for example when they're hired
Applications Write Files the application against the role
Attachments Write Uploads the candidate's CV

Optional

Each feature appears as a row under Capabilities once you connect.

Permission Access Feature Why Voyse needs it
Prospect details Read CRM Prospects Lists your prospects
Applications Read CRM Prospects Links each prospect to their candidate details
Notes Read and write Candidate Notes Writes a note on the candidate summarising what they asked your assistant and engaged with before applying
Job notes Read and write Job Notes Writes the weekly note on each role
Users Read Job Notes, Hiring manager contacts Attributes job notes to a user, and finds each hiring manager's email address
Custom fields Read Custom Fields Lists your custom fields for the salary setting
Job hiring managers Read Hiring manager contacts Finds who manages each role, for post-hire feedback

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.

The rows match the features in the Optional table above. Grant every permission listed against a feature: CRM Prospects and Hiring manager contacts can show as granted with only part of their set, then come back incomplete.

Two settings worth filling in

Once Custom Fields is granted, a selector appears under Capabilities, and a second 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.
  • 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.

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