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] |
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 Verificationstage 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.

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¶
-
Open API Credential Management in the Dev Center sidebar.

-
Click Create new API credentials, top right.

-
Fill in:
- API Type:
Job Board - Partner:
Polyguardif it is listed, otherwiseUnlisted vendor - Description:
Polyguard: Job Board
- API Type:
- Click Manage permissions and grant:
- POST Submit Application
- 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.
- Configure → Custom Options → Application → Add Field.
- Fill in:
- Name:
Polyguard Verification Token - Field type:
Short textbox
- Name:
- Save, reopen the field, and note the generated field key, for example
polyguard_verification_token.
3d. The Human Verification stage¶
- Open a job → Job Setup → Interview Plan → Add stage → Create a custom stage.
- Fill in:
- Stage name:
Human Verification, spelled exactly - Position: second, immediately after the first stage
- Stage name:
- 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.

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.

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.

| 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¶
- 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.
- Click Connect Greenhouse. You are sent to Greenhouse; sign in if prompted and approve the Polyguard partner app.
- 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.

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¶
- Apply through the careers site and complete the Trust Check on a phone.
- In Greenhouse, confirm the candidate appears, sits in Human Verification, and has the Polyguard Verification Token field populated.
6.3 Direct apply¶
- Apply through your public Greenhouse board, using a different email address than 6.2.
- Confirm the Trust Check email arrives.
- 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¶
- Email: [email protected]
- Console: console.polyguard.ai
- Sending Trust Check emails from your own domain: Sending From Your Domain
Greenhouse documentation¶
- Create a job board API key for an integration
- Create a new custom application field
- Interview plan overview
- Edit job stage in bulk
- Job Board API
For Greenhouse platform issues unrelated to Polyguard, contact your Greenhouse administrator or Greenhouse Support.