Checkr — Integration Setup
CMDash reads screening status only. It never reads the report, the records in it, or the
clear/consideroutcome. See What CMDash deliberately does not read below — that section is the most important one on this page.
Prerequisites
- A Checkr account with API access
- Permission to create a secret API key
- CMDash Essentials tier or above
Step 1: Create an API key
- Sign in to the Checkr dashboard.
- Go to Account settings → Developer settings.
- Under API keys, copy your Secret key (
live_…for production,test_…for a sandbox).
Use a Production key for real evidence. A test key returns sandbox candidates, which will produce a screening coverage number that describes nothing.
Step 2: Connect in CMDash
- Navigate to Integrations in your CMDash dashboard.
- Find Checkr and click Connect.
- Enter your Secret key.
- Click Save & Test Connection.
Checkr authenticates with HTTP Basic using the key as the username and an empty password. CMDash handles that; you paste the key only.
What Syncs
| Data | Checkr API | Purpose |
|---|---|---|
| Candidate id, name, work email | GET /v1/candidates | Identifies who was screened, and joins to your HRIS roster and identity provider |
| Screening lifecycle, package name, request and completion dates | GET /v1/invitations | Evidences that screening happened and when |
What CMDash deliberately does not read
CMDash calls those two endpoints and no others. It never calls /v1/reports, /v1/screenings/*, or any per-record endpoint. The following never leave Checkr, even where Checkr returns them inline on an object CMDash does read:
- The report and every record in it — criminal records, charges, dispositions, sentences, arrest data, sex-offender registry results
- The outcome —
clearandconsiderare both stored ascompleted, and the distinction is discarded at the point of ingestion - National identifiers — SSN,
ssn, tax ids - Date of birth, driver's licence number, home address, personal phone
- Motor-vehicle records, credit reports, drug-test results, employment- and education-verification contents
Why the outcome is dropped. The control being evidenced is SOC 2 CC1.4: background screening is performed on personnel per policy. That is answered by "a check was run for this person and it finished, on this date". What the check found answers a different question — one belonging to your HR process, inside Checkr, under FCRA adverse-action procedure. Putting it in a compliance dashboard your account admins can read, to evidence a control that never asked for it, is not a trade CMDash makes on your behalf.
This is not a filter applied after storage. The distinction is discarded in the adapter, before anything is written — never received, rather than received and hidden.
How the numbers are computed
- Screening coverage is completed checks over checks still in flight or done. Canceled and expired screenings are excluded from both sides: a canceled screening is not an incomplete one — the request was withdrawn, usually because the candidate never joined. Counting it as a failure would mean a company that screens everyone it hires can never reach 100% because of the offers it withdrew.
- Stale pending count is screenings outstanding for more than 30 days. This is the number to act on. The realistic CC1.4 failure is not "nobody was screened" — it is a screening that was requested and never came back, which a coverage percentage counts as merely not-yet-done, forever.
- A candidate with no invitation is reported as pending, dated from their candidate record, so someone who was created and never actually screened ages into the stale count rather than sitting invisible.
- Re-screening: where a candidate has several invitations, the most recent one is used. An older completed record would otherwise mask an outstanding re-check.
Controls this evidences
CMDash seeds a suggested mapping for SOC 2 CC1.4 (stalePendingCount == 0).
Keyed on a count of zero rather than a coverage percentage for the reason above: one screening stuck for two months is a real finding, and a 95%-coverage threshold would pass an organisation with exactly that gap.
Pair this with an HRIS integration (BambooHR, Rippling, Gusto, Workday). The roster says who works here, Checkr says who was screened, and the gap between the two is the evidence an auditor actually samples.
Troubleshooting
- 401 Unauthorized: the key is wrong, or a test key is being used against production data. Check Account settings → Developer settings.
- Coverage is lower than expected: look at
stalePendingCountfirst. Outstanding invitations candidates never completed are the usual cause. - A screened employee is missing: they were screened under a different Checkr account, or they exist as a candidate with no invitation (reported as pending).
- Candidate count is lower than Checkr shows: the 5,000-candidate ceiling truncated the walk. Check the sync log for the warning.
Rate Limits & Sync Behavior
| Setting | Value |
|---|---|
| Sync frequency | Every 4 hours by default (syncInterval is configurable per connection) |
| Pagination | per_page/page, 100 per page, capped at 5,000 candidates and 5,000 invitations per sync |
| Rate limit handling | Routed through CMDash's shared token-bucket limiter at 300 req/min |
| Circuit breaker | Repeated failures open the breaker and the sync is skipped |
| Failed sync retry | Job queue retries 3 times with exponential backoff (starting at 30s) — see docs/developers/dead-letter.md |
Credential Rotation
Checkr secret keys do not expire. Rotate at least annually.
- In Checkr: Account settings → Developer settings → generate a new secret key.
- In CMDash: Settings → Integrations → Checkr → Edit, enter the new key, Save.
- Confirm a successful sync, then revoke the old key.
Known Limitations
- No adjudication state. Whether you engaged, or issued a pre/post-adverse-action notice, is not read. That is an HR decision with a legal process around it, and it is not CC1.4 evidence.
- No per-screening detail. You cannot drill from CMDash into what a check covered beyond the package name. Follow the candidate into Checkr for that.
- The 5,000-record ceiling is a truncation, not a sample. Larger accounts are cut off and the sync log carries a warning; coverage is computed over the truncated set.
- Continuous Check is not read separately. Ongoing-monitoring subscriptions surface as further invitations rather than as a distinct signal.
- No write-back. CMDash never orders a screening, never cancels one, and never sends candidate data to Checkr.