Skip to content

Polyguard PreScreen for Greenhouse

Product Polyguard PreScreen
ATS Greenhouse (Job Board API + Harvest v3, partner OAuth)
Console console.polyguard.ai
Setup time approximately 15 minutes
Contact [email protected]

Download this guide as a PDF


1. Overview

PreScreen gates every application on a Polyguard Trust Check: a short check, completed on the candidate's phone, that confirms a real person is applying. Unverified candidates are held in the first stage of your pipeline; verified ones are advanced automatically, with the verification recorded on the application.

How it works

Applications reach Greenhouse two ways, and PreScreen covers both.

Where the candidate applies How it is gated
Hosted apply Your Polyguard careers site The form holds the submit until the Trust Check passes, then submits to Greenhouse with the verification attached
Direct apply Greenhouse itself, via LinkedIn, Indeed, or a referral Greenhouse notifies Polyguard, which emails the candidate a Trust Check and holds them in the first stage until they complete it

Most applications arrive the second way, which is why the Greenhouse connection in Section 5 is not optional: connecting is what registers the webhook that tells Polyguard about each new application.

What you will configure

  • A PreScreen app in the Polyguard Console, with its own hostname
  • A Job Board API key, used to submit hosted applications to Greenhouse
  • A custom application field that records the verification
  • A Human Verification stage on each protected job
  • The Greenhouse connection: a one-time partner authorization that lets Polyguard move applications and registers the application webhook for you

Who does what

Steps marked (Polyguard) need a Polyguard staff account. Everything else an account admin can do.


2. Prerequisites

Requirement Details
Greenhouse access A user who can manage Dev Center (typically Site Admin), edit interview plans, and approve the Polyguard partner app for your Greenhouse account
Polyguard account Console access at console.polyguard.ai with the admin role
Brand assets Logo, exact brand colors, and the company display name for the careers site
A test job One open job you can apply to end to end before going live

Secrets are shown once

Greenhouse displays the Job Board API key exactly once, and the Polyguard Console stores it write-only, showing only the last 4 characters afterwards. Copy it into the Console the moment you create it. It is the only Greenhouse secret you handle: the Greenhouse connection in Section 5 keeps its tokens on the Polyguard server.


3. Collect your Greenhouse values

The Job Board API key lives under Configure (⚙️) → Dev Center. The custom field and the pipeline stage are elsewhere in Configure.

Greenhouse Dev Center

Work through 3a to 3d and keep the values to hand. You will paste them into the Console in Section 4.

3a. Job Board API key

  1. Open API Credential Management in the Dev Center sidebar.

    Dev Center with API Credential Management highlighted

  2. Click Create new API credentials, top right.

    The Create new API credentials button

  3. Fill in:

    • API Type: Job Board
    • Partner: Polyguard if it is listed, otherwise Unlisted vendor
    • Description: Polyguard: Job Board
  4. Click Manage permissions and grant:
    • POST Submit Application
  5. Copy the key, then click I have stored the API Key.

Demo mode

Leaving this blank later keeps the careers site in demo mode: it shows exactly what it would have submitted, without posting to Greenhouse. That is useful for a dry run before going live.

3b. Board token

The slug in your public board URL, job-boards.greenhouse.io/<your-board-token>. Confirm it returns your live roles. No key is needed, these endpoints are public:

curl -s "https://boards-api.greenhouse.io/v1/boards/<your-board-token>/jobs" | head -c 300

3c. Custom field for the verification token

One org-wide field, created once. See Greenhouse's Create a new custom application field.

  1. Configure → Custom Options → Application → Add Field.
  2. Fill in:
    • Name: Polyguard Verification Token
    • Field type: Short textbox
  3. Save, reopen the field, and note the generated field key, for example polyguard_verification_token.

3d. The Human Verification stage

  1. Open a job → Job Setup → Interview Plan → Add stage → Create a custom stage.
  2. Fill in:
    • Stage name: Human Verification, spelled exactly
    • Position: second, immediately after the first stage
  3. Save.

Greenhouse does not allow a custom first stage. Applications land in the first stage, unverified candidates are held there, and PreScreen advances them into Human Verification once they pass.

Every protected job needs the stage

Teams whose pipelines name these stages differently can be listed under Pipeline stages by team on the Candidate verification card of the PreScreen settings page, with their own initial and verified stage names.

The stage must exist, with the same name and in second position, on every job you want protected. Use Edit job stage in bulk to roll it out across open jobs.


4. Configure the app in Polyguard

4a. Create the PreScreen app (Polyguard)

Console → Create App → app type PreScreen.

Create a PreScreen app in the console

Creating it reserves a hostname of the form {account-slug}.prescreen.polyguard.ai. A second tenant on the same account gets -2, -3, and so on.

4b. Check the hostname (Polyguard to change)

Settings → Hostnames shows the host this tenant is served on. Account admins can read it; only Polyguard staff can change it.

Hostnames card

It matters beyond the address bar: the address Polyguard delivers verification results to is built from it, and so is the default endpoint of the webhook Polyguard registers in Section 5.

Note

The reserved name is not a live site until Polyguard attaches it to the tenant's deployment. That is a Polyguard task and does not block the rest of this guide.

4c. ATS connection

Settings → ATS connection. Under Provider, pick Greenhouse (Harvest v3). The fields appear under Greenhouse Parameters.

ATS connection card with Provider set to Greenhouse (Harvest v3)

Field Value From
Board token your board slug 3b
Job Board API key the Job Board key; blank keeps submits in demo mode 3a
Gate stage name filled in as Human Verification; change it only if your stage has another name 3d
Polyguard field key filled in as polyguard_verification_token; change it if Greenhouse generated a different key 3c
Webhook endpoint URL optional; the greyed-out address is the one Polyguard registers when the field is blank Section 5
Manual source names optional, defaults to Internal Applicant sources never emailed a Trust Check

Click Save ATS configuration. Secrets clear from the form on save and show their last 4 characters afterwards; leaving a secret blank keeps the stored value rather than clearing it.

4d. Expiry of emailed Trust Checks

On the Candidate verification card, under Auto-archive. The card shows these settings once the ATS configuration has been saved.

Field Value
Trust Check expiry (days) 1 to 7; 3 when not set
Rejection reason id optional; Greenhouse's default is used when blank
Reject application on expiry tick it to reject, in Greenhouse, an application whose emailed Trust Check expires; unticked, the application stays held in the first stage

Click Save switches.


5. Connect Greenhouse

Greenhouse notifies Polyguard whenever a candidate submits an application, and Polyguard moves verified candidates and records the verification token through the Greenhouse API. Both run through the Polyguard partner app, authorized once from the Console. There is nothing to create in Dev Center: no Harvest key, no web hook, no secret.

5a. Choose the authorizing user

Greenhouse attributes every action Polyguard takes (moving an application into Human Verification, writing the verification token to the custom field, rejecting an expired application) to the user who approves the connection. Sign in to Greenhouse as a dedicated recruiting-ops user or an Integration System User rather than a personal account, so the attribution does not change when staff do. That user must be able to edit and move applications on the protected jobs.

5b. Connect

  1. Connect Greenhouse is at the bottom of the ATS connection card, below Save ATS configuration. Until the provider and its fields are saved, the button is unavailable and the note beside it reads Save these settings before connecting. Once they are saved, the status beside it reads Partner OAuth: not connected.
  2. Click Connect Greenhouse. You are sent to Greenhouse; sign in if prompted and approve the Polyguard partner app.
  3. You land back in the Console with the banner Greenhouse connected and webhook registered. The status now reads Partner OAuth: connected. and the button becomes Reconnect Greenhouse.

Connect Greenhouse button at the bottom of the ATS connection card, with the Partner OAuth status beside it

The info icon beside the button summarizes what happens: connecting authorizes Polyguard with your Greenhouse account and registers the application webhook automatically; tokens stay on the server.

What the connection grants

Permission Why PreScreen needs it
List, create, update and delete webhooks Register the application webhook and keep it current
List applications Read application status and source
Move applications Advance a verified candidate into Human Verification
Update applications Write the verification token to the custom field
Reject applications Reject an application whose Trust Check expired, when that option is on
List job interview stages Find the gate stage in a job's pipeline

Polyguard registers webhooks for the Candidate has submitted application event and for job and job post changes. Nothing needs to be created or edited under Dev Center → Web Hooks.

Tokens refresh automatically

Polyguard refreshes its access token itself. If the Console ever shows Partner OAuth: not connected. again, click Connect Greenhouse and approve the app once more.


6. Verification

Run all four before going live.

6.1 Listings

Open the careers site at your hostname. Your live Greenhouse roles should appear, in your brand.

6.2 Hosted apply

  1. Apply through the careers site and complete the Trust Check on a phone.
  2. In Greenhouse, confirm the candidate appears, sits in Human Verification, and has the Polyguard Verification Token field populated.

6.3 Direct apply

  1. Apply through your public Greenhouse board, using a different email address than 6.2.
  2. Confirm the Trust Check email arrives.
  3. Complete it and confirm the application advances into Human Verification.

Use a different email

Reusing the one from 6.2 matches the verification already cached for that job, so the application advances immediately and the email path is never exercised.

6.4 Manual override

Advanced → Manual verification, with the link id of a candidate you confirmed some other way, advances that application. One use per link.


7. Using PreScreen

Day to day

Nothing to do. Applications arrive, candidates verify, and verified candidates advance into Human Verification with the token recorded on the application. Candidates who never verify stay in the first stage until their Trust Check expires.

Operator tools

Console location What it does
Advanced → Manual verification Advance a candidate verified out of band
Verification → Test email Send yourself a Trust Check to confirm delivery
Analytics Trust Check funnel for the account
Settings → Branding Company name, colors, logo and theme

Adding a job later

New jobs need the Human Verification stage in second position (3d). Everything else is account-wide and already configured.


8. Troubleshooting

Nothing reaches Polyguard at all

The Greenhouse connection is not established, so no webhook is registered and direct applies are never seen. Open Settings → ATS connection and read the status beside the Connect Greenhouse button at the bottom of the card. If it says Partner OAuth: not connected., click Connect Greenhouse (Section 5); the webhook is registered again as part of connecting.

The candidate advances but the token field stays empty

The Greenhouse user who approved the connection cannot edit applications on that job. The token write is refused while the stage move still succeeds, so nothing looks broken. Click Reconnect Greenhouse and approve the app as a user who can edit applications (5a).

A change in the Console has not taken effect

Configuration is cached for 60 seconds. Wait a minute and retry. Branding is the exception: see below.

Branding changes do not appear on the careers site

Give it up to an hour. The careers index and the job pages are rendered ahead of time and refreshed hourly, so a branding change is picked up at the next refresh rather than on the next page load.

A field left blank in the Console falls back to the deployment's own configuration, and a value the site rejects as unsafe (a logo or site URL that is not https://, a color that is not a valid CSS color) falls back the same way, so check the value if one field stays on the old branding while the rest update.

The Trust Check invitation email still takes its company name from the deployment configuration, not from these fields.

The careers site shows no roles

Either the board token is wrong (3b), or the provider selected in the Console does not match the one the deployment is running. A mismatch is silent: the Console settings are simply ignored.

A candidate was never emailed a Trust Check

Applications with no source, or with a source listed in Manual source names, are treated as recruiter entries and deliberately never emailed. A recruiter adding a candidate by hand has already decided they belong in the pipeline.


9. Support

Greenhouse documentation

For Greenhouse platform issues unrelated to Polyguard, contact your Greenhouse administrator or Greenhouse Support.