How do I set up the Checkr integration?

Last updated: July 29, 2026

This walks you through connecting your Checkr account to Onboarded over OAuth, waiting for credentialing, and adding a Checkr form to a task so background checks run during onboarding. It also covers the field that has to sit on the employer page for report statuses to land — the most common reason a check looks stuck.

Before you start

You need account-owner or admin permissions in Onboarded.
You need a Checkr account. You connect it by signing in to Checkr — there are no API keys to copy or paste. If you need a Checkr account, please reach to Onboarded for preferential pricing.
Set up at least one screening Package in your Checkr account before you start, since you'll pick one when you add the form.

Steps

Setup has three phases: connect your Checkr account once at the account level, add a Checkr form to each task that needs a background check, then confirm that form carries both Checkr fields.

Phase 1 — Connect your Checkr account

Navigate to Account Settings → Integrations and find Checkr under Background Checks.
Click Configure. A side panel opens titled Configure Checkr.
Click Connect to Checkr. Onboarded redirects you to Checkr to authorize the connection.
Sign in to Checkr and approve access. Checkr returns you to Onboarded, and the panel shows your connection status.
You should see the Checkr card marked as connected.

You can connect before you can run checks. Right after connecting, the status usually reads Connected, Pending Credentialing with an orange dot. Checkr credentials every new account before it can order reports — this normally takes less than one business day. You can keep building forms while you wait, but no checks will run until the status turns green and reads Connected and Credentialed.

Phase 2 — Add a Checkr form to a task

Background checks run through a Checkr form that you attach to a task. Connecting the account alone doesn't order any checks.

Click Add form from the Checkr panel (or open the form library and add the Checkr form there), then choose the task it belongs to.
Choose a Package. This is the Checkr screening package that gets ordered — the list comes straight from your Checkr account, with each package's price beside its name. This field is required.
Choose a Work Location. Pick Employee Address, Employer Address, or Job Address — this tells Checkr which address to use for the check. This field is required.
Optionally choose a Node. Nodes are Checkr's way of grouping checks under a part of your hierarchy (a brand, region, or segment). Leave it on None to use your account default. Picking a node narrows the Package list to the packages that node allows, so set the node first.
Save the form.

Phase 3 — Confirm the form has both Checkr fields

A working Checkr form needs two Checkr fields on the same task — one on a page assigned to the employee, one on a page assigned to the employer or to system. They do different jobs, and the page's assignee is what decides which job a field does.

Page assignee	`Mode`	What the field does	What you configure on it
`employee`	`Invitation`	Orders the check — Checkr emails the candidate an invitation to enter their own information.	`Package`, `Work Location`, and optionally `Node`.
`employer` or `system`	`Report`	Receives the report — this is where Checkr's report status and adjudication updates get written, and where your team reads them.	Nothing. `Mode` is read-only and no package or location options appear.

Open the form in the builder and find the page assigned to the employee. Confirm it has a field of type Integration with the integration set to Checkr, and that its Mode dropdown reads Invitation.
Open the page assigned to the employer (or to system) on that same task. Confirm it also has an Integration field set to Checkr, and that its Mode reads Report.
You don't set Mode yourself — it's derived from the page's assignee and shown greyed out. If it reads Report, the field is configured correctly. That's the only value it needs.
Deploy the form version once both fields are in place.

If the employer page has no Checkr field, the check still runs but its result never arrives. Checkr sends the report back to Onboarded, Onboarded looks for a Report-mode Checkr field on that task, finds none, and drops the update. Nothing errors on screen — the task just keeps showing whatever the invitation last said. The Checkr form in the form library ships with both pages, so this usually shows up on forms that were built by hand or copied from an older version.

If the report status doesn't match Checkr

The symptom looks like this: Checkr's dashboard shows the report as Clear, and Onboarded still shows the task as Pending or Cancelled. Work through these in order.

Check the employer page first. Confirm the Report-mode Checkr field described in Phase 3 exists on that task and that the form version carrying it is deployed. A missing field is the most common cause by a wide margin, and it produces exactly this symptom. Add the field, deploy the form, and reach out to Onboarded to backfill the statuses that were already dropped — new statuses will flow on their own, but ones missed while the field was absent need a backfill.
Check that the task is still open. Report tasks stay open on purpose so they can keep receiving adjudication updates. A task marked complete or expired stops accepting them, so a report that finishes afterward won't move the status.
Read the status labels literally. A cancelled invitation and a clear report can coexist — if the candidate got a second invitation, the first one stays Cancelled while the report from the second one comes back clear. Confirm you're comparing the same Checkr object, not an earlier invitation.
If all three check out, contact Onboarded with the task ID. Checkr delivers statuses over webhooks, and a delivery that failed on the Checkr side can be retried from our end.

Two smaller things worth knowing while you're in the form. If the Package or Node dropdown is empty, that data hasn't been set up on the Checkr side yet — add the package or node in your Checkr account, then reopen the form to refresh the options. If a dropdown shows a value followed by (removed), the package or node you'd selected no longer exists in Checkr; pick a current one before you deploy.

Verify

On Account Settings → Integrations, the Checkr card shows as connected. Once credentialing finishes, the status reads Connected and Credentialed with a green dot — that's when checks can run.

To confirm the form works end to end, add the Checkr form to a test placement and complete the task. The employee page produces a Checkr invitation. Once the candidate completes it and Checkr finishes the report, the employer page shows a Checkr Background Check Status card with the report status on it. Seeing that card populate is the real confirmation — it means the report path is wired, not just the invitation. If nothing happens at all, confirm the connection status is green; a check ordered while the account is still pending credentialing won't process.

Checkr API reference: docs.onboarded.com
Understanding Checkr packages, nodes, and work locations (Reference — coming)
How do I read a Checkr report status in Onboarded? (How-to — coming)