# Checkr
SureCloud connects to Checkr to retrieve background check records, candidate screening statuses, and adjudication outcomes. This data allows SureCloud to verify that pre-employment screening controls are operating as required — confirming that checks are initiated at the point of hire, completed within defined timeframes, and that no candidates have been onboarded without a completed or waived background check on record.
## Authentication and setup
Checkr authenticates via API key. SureCloud uses a read-only API key scoped to your Checkr account.
{% hint style="info" %}
SureCloud requires a **live** (production) API key, not a test key. Test keys return synthetic data and will not reflect your actual hiring records.
{% endhint %}
{% stepper %}
{% step %}
**Generate a Checkr API key**
Log in to your Checkr Dashboard at [dashboard.checkr.com](https://dashboard.checkr.com/). Navigate to **Account Settings → Developer Settings → API Keys** and click **Create API Key**. Give it a descriptive name such as `SureCloud CCM`. Copy the key immediately — it is only shown once.
{% endstep %}
{% step %}
**Enter the API key in SureCloud**
In SureCloud, go to **Integrations → Checkr → Connect**. Paste the API key into the **API Key** field. Select the environment (Production) and click **Save**.
{% endstep %}
{% step %}
**Test the connection**
Click **Test Connection**. SureCloud will call `GET /v1/account` to verify the key is valid and the account is active. A green status confirms the connection is live.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
Store the API key securely after copying it from Checkr. SureCloud encrypts it at rest, but you should treat it as a sensitive credential. Rotate it every 90 days and update it under **SureCloud → Integrations → Checkr → Edit Connection**.
{% endhint %}
## Endpoints
| API Call | Use Case |
| ---------------------- | ------------------------------------------------------------------------------- |
| `GET /v1/account` | Verify account is active; used during connection test |
| `GET /v1/candidates` | Enumerate all candidates with associated background check records |
| `GET /v1/reports` | Retrieve background check reports including status and completion date |
| `GET /v1/reports/{id}` | Fetch individual report detail including adjudication outcome and package type |
| `GET /v1/invitations` | List outstanding invitations to identify checks initiated but not yet completed |
| `GET /v1/packages` | Enumerate configured check packages to validate screening scope |
## Pagination
`GET /v1/candidates` and `GET /v1/reports` return up to 100 records per page. SureCloud uses the `next_href` field from each response to retrieve subsequent pages, continuing until `next_href` is absent.
```
GET /v1/reports?per_page=100&page=2
```
`GET /v1/invitations` uses the same page-based mechanism. `GET /v1/account` and `GET /v1/packages` return single objects with no pagination.
## Required permissions
Checkr API keys are account-scoped and read-only by default. The key SureCloud uses requires access to the following resource types within your Checkr account:
* Candidates (read)
* Reports (read)
* Invitations (read)
* Packages (read)
* Account (read)
No special elevated permissions are required beyond standard API key access. If your Checkr account uses sub-accounts (nodes), ensure the API key is generated at the root account level so SureCloud can access all hiring records.
## Polling frequency
| Data Type | Interval |
| ------------------------------------- | -------------- |
| Background check reports and statuses | Every 24 hours |
| Candidate records | Every 24 hours |
| Outstanding invitations | Every 12 hours |
| Check packages | Every 24 hours |
## Troubleshooting
Connection test fails with 401 Unauthorized
The API key is invalid, has been revoked, or is a test key rather than a live production key. Regenerate a new API key in the Checkr Dashboard under **Account Settings → Developer Settings → API Keys**, ensuring the environment is set to **Production**. Update the key in **SureCloud → Integrations → Checkr → Edit Connection**.
Reports return empty or candidate count is unexpectedly low
This typically occurs when the API key was generated on a sub-account (node) rather than the root account. SureCloud will only see records accessible to the account that owns the key. Log in to the Checkr root account and regenerate the key there, then update the connection in SureCloud.
Invitations are missing for recently created candidates
Invitations in Checkr expire after a period of inactivity. SureCloud collects active and recently expired invitations, but invitations older than 30 days that were never actioned may not be returned by the API. Check the Checkr Dashboard directly for historical invitation records if needed.
Rate limit errors (429 Too Many Requests)
Checkr enforces rate limits on its API. SureCloud spreads collection across polling windows to avoid hitting these limits, but if your account has a very large volume of candidates, temporary 429 errors may appear in the integration logs. SureCloud will automatically retry on the next polling cycle. If the issue persists, contact SureCloud Support to adjust the polling interval for your account.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/checkr.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.