Checkmate is a background check and candidate verification platform. Checkmate's integration with Greenhouse Recruiting allows recruiters to run and track a candidate's background check without leaving Greenhouse—simply by moving a candidate into a Background Check stage, and Checkmate creates the candidate, posts progress notes, and writes the status and final report link back onto the Greenhouse application.
Configure the Checkmate integration
Checkmate uses the OAuth 2.0 authorization-code flow.
In Checkmate, go to Settings > Integrations > Greenhouse and toggle it on.
You'll be redirected to Greenhouse to authorize Checkmate. Review the requested permissions and select Authorize.
We recommend authorizing as a dedicated service account so that all notes and field updates Checkmate makes are clearly attributed to the integration in your audit trail. See Greenhouse's guide on connecting to Harvest v3 partner integrations.
You're returned to Checkmate with the integration marked Connected.
On connect, Checkmate automatically registers the required webhook via the Harvest API—no manual webhook creation is needed (see "How Checkmate registers the webhook" below).
The integration requests the following scopes:
candidates.read-
applications.read,applications.write notes.writecustom_fields.write-
webhooks(to register the stage-change webhook on your behalf)
Create the Background Check stage
Checkmate triggers when a candidate enters a stage named exactly Background Check (case-insensitive).
Go to Configure > Job Templates (or an individual job) > Job Stages.
Add a stage named Background Check.
If the stage is named anything else (e.g. "BG Check"), Checkmate acknowledges the event and takes no action.
Create two custom application fields
Checkmate writes the check status and reports the URL back to the application. Create both fields; the auto-generated name_key must match the table exactly.
Click the Configure icon, then Custom Options on the left.
Click Application.
Click Add field and create each field below.
| Field name | name_key (must match) | Type |
| Checkmate Background Check Status | checkmate_background_check_status |
Short text |
| Checkmate URL | checkmate_url |
Short text (URL) |
If a name_key doesn't match, edit the field and override the key.
How Checkmate registers the webhook
As an official Greenhouse partner, Checkmate manages the webhook for you via the Harvest API; you do not need to create one manually. When you connect (Step 1), Checkmate registers a webhook with these settings:
- Name: Checkmate Background Check
- When: Candidate has changed stage
- Endpoint URL: Checkmate's secure endpoint for your organization
- Secret Key: generated by Checkmate and used to HMAC-verify every incoming event
The webhook fires on every stage change; Checkmate filters server-side to only act on the Background Check stage.
Data Checkmate reads from Greenhouse
On each stage entry, Checkmate reads these fields from the webhook payload:
| Greenhouse field | Used in Checkmate as |
application.candidate.first_name |
Candidate first name (required) |
application.candidate.last_name |
Candidate last name (required) |
application.candidate.email_addresses[*] |
Primary email (required) |
application.candidate.phone_numbers[*] |
Primary phone (optional) |
application.jobs[0].name |
Job role shown in Checkmate |
application.jobs[0].departments[0].name |
Department shown in Checkmate |
application.id |
Stored as the Checkmate reference GH-<id>
|
application.candidate.id |
Candidate id used on write-back calls |
Only the first job and its first department are used for candidates on multiple jobs.
Data Checkmate writes to Greenhouse
Checkmate writes to the two custom application fields from Step 3 and posts an admin-only note on the candidate. It does not modify any other Greenhouse data.
Use the Checkmate integration
Trigger a background check
Once configured, a recruiter runs a check entirely from Greenhouse:
Open a candidate's application (for example, Ruth Rodriguez, applying for IT Support Engineer) and move it into the Background Check stage.
Within a few seconds, Checkmate creates the candidate and updates the application:
Checkmate Background Check Status → Candidate Created - Select Checks
Checkmate Report URL → a Checkmate link
A note is added to the candidate: "Checkmate Background Check for IT Support Engineer: Candidate created. Click here to select checks."
Click the link in the note (or the Report URL field) to open the candidate in Checkmate, then choose which checks to run and submit.
The status field updates to Checks Selected - In Progress while the checks run.
When all checks complete, Checkmate sets the status to Completed and the Report URL resolves to the finished report.
Status values Checkmate writes
| Value | Meaning |
| Candidate Created - Select Checks | Candidate received; recruiter needs to choose checks |
| Checks Selected - In Progress | Checks are running |
| Completed | All checks complete; report URL populated |
| Error - Email Required | Candidate had no email address |
| Error - Required Fields Missing | Candidate was missing a first or last name |
| Error | Generic failure—contact Checkmate support |
| Deleted from Checkmate | Candidate was removed from Checkmate |
Sending additional candidate information
The integration sends the fields listed under Data Checkmate reads from Greenhouse. If you'd like additional candidate information passed to Checkmate, contact Checkmate Customer Success with the list of fields you'd like to add.
Additional resources
Checkmate support
Support email: team@checkmate.tech
Support is 24/7 in-app.
Help center: https://docs.checkmate.tech/
Common questions
- Nothing happened when I moved a candidate onto the stage. Confirm the stage is named exactly Background Check and that the integration shows as Connected in Checkmate.
-
The status/report fields aren't updating. Confirm the authorizing user has permission to edit application custom fields, and that the two
name_keys match exactly. - Can I re-run a completed check? Moving an already-completed candidate back into the stage does nothing. Delete the candidate in Checkmate first, then move them into the stage again.