> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/checkr.md).

# Checkr

Screen candidates with Checkr background checks: create candidates, send invitations, order and read reports, and manage adverse action.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| Checkr    | API Key        |

#### Checkr

Connect to Checkr to screen candidates with background checks.

**Set up in Checkr**

1. Prepare the Checkr account or service that the workflow will access. Grant access to the required resources and operations.
2. **API Key:** Your Checkr secret API key, from Account Settings > Developer Settings in the Checkr Dashboard. It must match the environment below.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Checkr**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required                 | What to enter                                                                                                                                                                                                          |
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Key       | Yes                      | Your Checkr secret API key, from Account Settings > Developer Settings in the Checkr Dashboard. It must match the environment below. [Provider instructions](https://dashboard.checkr.com/account/developer_settings). |
| Environment   | Optional / as applicable | Which Checkr environment issued the key. Production orders real background checks and bills for them; staging is Checkr's sandbox.                                                                                     |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **Checkr** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Candidate

Register a person in Checkr so you can invite them to a background check or order one directly.

**Inputs**

| Field                      | Type            | Required | Description                                                                                                                |
| -------------------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| Email                      | string          | Yes      | Candidate's email address. Checkr sends the invitation and notices here.                                                   |
| First name                 | string          | No       | Candidate's legal first name.                                                                                              |
| Last name                  | string          | No       | Candidate's legal last name.                                                                                               |
| Phone                      | string          | No       | Mobile phone number; recommended for identity verification screenings.                                                     |
| Your reference ID          | string          | No       | Your own identifier for this person (ATS or HRIS id). Searchable in Checkr.                                                |
| Show advanced fields       | boolean         | No       | Reveal middle name, date of birth, SSN, driver license, work location, geo, and copy-requested fields. Default: false.     |
| Middle name                | string          | No       | Candidate's middle name. Leave empty and tick 'No middle name' if they have none.                                          |
| No middle name             | boolean         | No       | Tick when the candidate has no middle name.                                                                                |
| Date of birth              | date            | No       | Date of birth. Needed for direct report orders.                                                                            |
| ZIP code                   | string          | No       | 5-digit US ZIP code. Needed for criminal screenings ordered directly.                                                      |
| Social Security Number     | secret          | No       | Only for direct report orders with criminal screenings. Prefer Invite Candidate so Checkr collects this securely.          |
| Driver license number      | string          | No       | Needed for Motor Vehicle Record screenings ordered directly.                                                               |
| Driver license state       | string          | No       | Two-letter US state that issued the license.                                                                               |
| Work location state        | string          | No       | State where the candidate will work. Required for hierarchy-enabled and non-US accounts.                                   |
| Work location city         | string          | No       | City where the candidate will work.                                                                                        |
| Work location country      | string          | No       | Two-letter country code. Defaults to US when empty.                                                                        |
| Geo                        | select (string) | No       | Compliance region configured in your Checkr account. Some accounts require one. Options load from the selected connection. |
| Candidate requested a copy | boolean         | No       | Tick if the candidate asked to receive a copy of their report.                                                             |

**Outputs**

| Field             | Type   | Description                                |
| ----------------- | ------ | ------------------------------------------ |
| Candidate ID      | string | Checkr id of the new candidate.            |
| Email             | string | Candidate email.                           |
| First name        | string | First name.                                |
| Last name         | string | Last name.                                 |
| Your reference ID | string | Your identifier.                           |
| Adjudication      | string | Adjudication of the latest report, if any. |

#### Get Candidate

Look up a candidate by Checkr ID, email or your reference ID, including their background check reports.

**Inputs**

| Field     | Type   | Required | Description                                               |
| --------- | ------ | -------- | --------------------------------------------------------- |
| Candidate | string | Yes      | Checkr candidate ID, email address, or your reference ID. |

**Outputs**

| Field             | Type          | Description                                     |
| ----------------- | ------------- | ----------------------------------------------- |
| Candidate ID      | string        | Checkr candidate id.                            |
| Email             | string        | Email.                                          |
| First name        | string        | First name.                                     |
| Last name         | string        | Last name.                                      |
| Phone             | string        | Phone.                                          |
| Your reference ID | string        | Your identifier.                                |
| Adjudication      | string        | Adjudication of the latest report.              |
| Report IDs        | string\_array | Ids of the candidate's reports.                 |
| Reports           | object\_array | The candidate's reports with status and result. |

#### Search Candidates

Find candidates by email, name, your reference ID, adjudication or creation date.

**Inputs**

| Field                | Type            | Required | Description                                                                                                                    |
| -------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Email                | string          | No       | Exact email address.                                                                                                           |
| Full name            | string          | No       | Candidate full name.                                                                                                           |
| Your reference ID    | string          | No       | Your own identifier for the candidate.                                                                                         |
| Adjudication         | select (string) | No       | Only candidates whose latest report has this adjudication. Available values: Engaged, Pre-adverse action, Post-adverse action. |
| Created after        | datetime        | No       | Only candidates created after this time.                                                                                       |
| Created before       | datetime        | No       | Only candidates created before this time.                                                                                      |
| Max results          | integer         | No       | How many candidates to return (1-100). Minimum: 1. Maximum: 100. Default: 25.                                                  |
| Show advanced fields | boolean         | No       | Reveal geo and page fields. Default: false.                                                                                    |
| Geo                  | select (string) | No       | Only candidates in this compliance region. Options load from the selected connection.                                          |
| Page                 | integer         | No       | Page number to continue from a previous search. Minimum: 1.                                                                    |

**Outputs**

| Field       | Type          | Description                                      |
| ----------- | ------------- | ------------------------------------------------ |
| Candidates  | object\_array | Matching candidates.                             |
| Total count | integer       | Total matches across all pages.                  |
| Next page   | integer       | Page number for the next batch, empty when done. |

#### Invite Candidate

Send a candidate a Checkr-hosted link to consent and complete their background check for a chosen package.

**Inputs**

| Field                 | Type            | Required | Description                                                                                                        |
| --------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| Candidate             | string          | Yes      | Checkr candidate ID or the candidate's email.                                                                      |
| Package               | select (string) | Yes      | Screening package to run. Options load from the selected connection.                                               |
| Show advanced fields  | boolean         | No       | Reveal node, work location, and tags fields. Default: false.                                                       |
| Node                  | select (string) | No       | Business unit or location node. Required on hierarchy-enabled accounts. Options load from the selected connection. |
| Work location state   | string          | No       | State where the candidate will work. Required on hierarchy-enabled accounts.                                       |
| Work location city    | string          | No       | City where the candidate will work.                                                                                |
| Work location country | string          | No       | Two-letter country code, defaults to US.                                                                           |
| Tags                  | string          | No       | Comma-separated tags to attach to the resulting report.                                                            |

**Outputs**

| Field           | Type     | Description                                           |
| --------------- | -------- | ----------------------------------------------------- |
| Invitation ID   | string   | Invitation id.                                        |
| Invitation link | string   | Link the candidate opens to complete the check.       |
| Status          | string   | pending, completed or expired.                        |
| Expires at      | datetime | When the link stops working.                          |
| Candidate ID    | string   | Candidate invited.                                    |
| Package         | string   | Package slug.                                         |
| Report ID       | string   | Report created once the candidate completes the flow. |

#### List Invitations

See pending, completed or expired background check invitations, optionally for one candidate.

**Inputs**

| Field                | Type            | Required | Description                                                                    |
| -------------------- | --------------- | -------- | ------------------------------------------------------------------------------ |
| Candidate            | string          | No       | Checkr candidate ID or email to filter by.                                     |
| Status               | select (string) | No       | Only invitations in this state. Available values: Pending, Completed, Expired. |
| Max results          | integer         | No       | How many invitations to return (1-100). Minimum: 1. Maximum: 100. Default: 25. |
| Show advanced fields | boolean         | No       | Reveal the page field. Default: false.                                         |
| Page                 | integer         | No       | Page number to continue from. Minimum: 1.                                      |

**Outputs**

| Field       | Type          | Description                        |
| ----------- | ------------- | ---------------------------------- |
| Invitations | object\_array | Matching invitations.              |
| Total count | integer       | Total matches.                     |
| Next page   | integer       | Next page number, empty when done. |

#### Cancel Invitation

Withdraw a pending background check invitation so the link stops working.

**Inputs**

| Field         | Type   | Required | Description                     |
| ------------- | ------ | -------- | ------------------------------- |
| Invitation ID | string | Yes      | Id of the invitation to cancel. |

**Outputs**

| Field         | Type     | Description                           |
| ------------- | -------- | ------------------------------------- |
| Invitation ID | string   | Invitation id.                        |
| Status        | string   | Status after cancellation.            |
| Canceled at   | datetime | When it was canceled.                 |
| Candidate ID  | string   | Candidate the invitation belonged to. |

#### Order Background Check

Order a background check report directly for a candidate whose details and consent you already collected.

**Inputs**

| Field                 | Type            | Required | Description                                                                                                        |
| --------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| Candidate             | string          | Yes      | Checkr candidate ID or the candidate's email.                                                                      |
| Package               | select (string) | Yes      | Screening package to run. Options load from the selected connection.                                               |
| Show advanced fields  | boolean         | No       | Reveal node, work location, and tags fields. Default: false.                                                       |
| Node                  | select (string) | No       | Business unit or location node. Required on hierarchy-enabled accounts. Options load from the selected connection. |
| Work location state   | string          | No       | State where the candidate will work. Required on hierarchy-enabled accounts.                                       |
| Work location city    | string          | No       | City where the candidate will work.                                                                                |
| Work location country | string          | No       | Two-letter country code, defaults to US.                                                                           |
| Tags                  | string          | No       | Comma-separated tags for the report.                                                                               |

**Outputs**

| Field                | Type     | Description                                        |
| -------------------- | -------- | -------------------------------------------------- |
| Report ID            | string   | Report id.                                         |
| Status               | string   | pending, complete, suspended, dispute or canceled. |
| Result               | string   | clear or consider once complete.                   |
| Package              | string   | Package.                                           |
| Candidate ID         | string   | Candidate screened.                                |
| Created at           | datetime | Order time.                                        |
| Estimated completion | datetime | Checkr's completion estimate.                      |

#### Get Report

Check a background check's status and result, who it is for, and optionally what each screening found.

**Inputs**

| Field                     | Type    | Required | Description                                                              |
| ------------------------- | ------- | -------- | ------------------------------------------------------------------------ |
| Report ID                 | string  | Yes      | Id of the report.                                                        |
| Show advanced fields      | boolean | No       | Reveal the include screening details option. Default: false.             |
| Include screening details | boolean | No       | Also return each screening's status, result and records. Default: false. |

**Outputs**

| Field                       | Type          | Description                                                    |
| --------------------------- | ------------- | -------------------------------------------------------------- |
| Report ID                   | string        | Report id.                                                     |
| Status                      | string        | pending, complete, suspended, dispute or canceled.             |
| Result                      | string        | clear or consider.                                             |
| Adjudication                | string        | engaged, pre\_adverse\_action, post\_adverse\_action or empty. |
| Assessment                  | string        | eligible, review or escalated on Assess-enabled accounts.      |
| Package                     | string        | Package.                                                       |
| Candidate ID                | string        | Candidate.                                                     |
| Candidate email             | string        | Candidate email.                                               |
| Candidate name              | string        | Candidate full name.                                           |
| Created at                  | datetime      | Order time.                                                    |
| Completed at                | datetime      | Completion time.                                               |
| Estimated completion        | datetime      | Checkr's estimate while pending.                               |
| Turnaround (seconds)        | integer       | Seconds from order to completion.                              |
| Includes canceled screening | boolean       | True if any screening was canceled.                            |
| Screenings                  | object\_array | Per-screening status and findings when requested.              |

#### List Packages

See the screening packages available on your Checkr account and their slugs.

**Inputs**

| Field                | Type    | Required | Description                                                                  |
| -------------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| Show advanced fields | boolean | No       | Reveal the result limit and page fields. Default: false.                     |
| Max results          | integer | No       | How many packages to return (1-100). Minimum: 1. Maximum: 100. Default: 100. |
| Page                 | integer | No       | Page number to continue from. Minimum: 1.                                    |

**Outputs**

| Field       | Type          | Description                        |
| ----------- | ------------- | ---------------------------------- |
| Packages    | object\_array | Packages on the account.           |
| Total count | integer       | Total packages.                    |
| Next page   | integer       | Next page number, empty when done. |

#### List Adverse Items

See the findings on a report that could justify an adverse action, with Checkr's assessment of each.

**Inputs**

| Field     | Type   | Required | Description        |
| --------- | ------ | -------- | ------------------ |
| Report ID | string | Yes      | Report to inspect. |

**Outputs**

| Field         | Type          | Description                                  |
| ------------- | ------------- | -------------------------------------------- |
| Adverse items | object\_array | Findings that may support an adverse action. |
| Count         | integer       | Number of items.                             |

#### Start Adverse Action

Begin Checkr's compliant pre- and post-adverse action notice process for a report you will not hire on.

**Inputs**

| Field                | Type     | Required | Description                                                                                        |
| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------- |
| Report ID            | string   | Yes      | Report the decision is based on.                                                                   |
| Adverse item IDs     | string   | No       | Comma-separated ids of the findings to cite. Empty cites all findings on the report.               |
| Show advanced fields | boolean  | No       | Reveal notice scheduling and delivery medium fields. Default: false.                               |
| Send post notice at  | datetime | No       | When to send the post-adverse action notice. Checkr defaults to 7 days after creation.             |
| Send by email        | boolean  | No       | Send the notices by email. Untick to stop email delivery.                                          |
| Send by postal mail  | boolean  | No       | Send the notices by postal mail to the candidate's postal address. Untick to stop postal delivery. |

**Outputs**

| Field                    | Type          | Description                             |
| ------------------------ | ------------- | --------------------------------------- |
| Adverse action ID        | string        | Adverse action id.                      |
| Status                   | string        | pending, complete, dispute or canceled. |
| Report ID                | string        | Report.                                 |
| Created at               | datetime      | When the pre notice was sent.           |
| Post notice scheduled at | datetime      | When the post notice will go out.       |
| Delivery state           | string        | Delivery state of the pre notice.       |
| Adverse item IDs         | string\_array | Items cited.                            |

#### Cancel Adverse Action

Stop an adverse action before the post-adverse action notice goes out, for example after the candidate disputes successfully.

**Inputs**

| Field             | Type   | Required | Description                                                                                                                                 |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Adverse action ID | string | Yes      | Id of the adverse action to cancel. Start Adverse Action returns it; otherwise copy it from the candidate's report in the Checkr Dashboard. |

**Outputs**

| Field             | Type     | Description                |
| ----------------- | -------- | -------------------------- |
| Adverse action ID | string   | Adverse action id.         |
| Status            | string   | Status after cancellation. |
| Report ID         | string   | Report.                    |
| Canceled at       | datetime | When it was canceled.      |

### Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

#### Report Completed

Fires when a background check report finishes, with its result and the candidate's details.

StackAI registers the Checkr webhook when you enable this trigger. The connection's API key must belong to the environment selected on it, and Checkr allows only two webhook URLs per account (dashboard and API combined): free one up under Account Settings > Developer Settings > Webhooks if setup fails. Deliveries arrive from a Checkr-Webhook/ user agent.

**Configuration**

| Field           | Type            | Required | Description                                                                                     |
| --------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Only for result | select (string) | No       | Only fire for reports with this result. Empty fires for all. Available values: Clear, Consider. |

**Event inputs**

| Field           | Type            | Required | Description                                           |
| --------------- | --------------- | -------- | ----------------------------------------------------- |
| Report ID       | string          | Yes      | Report id.                                            |
| Status          | string          | Yes      | Report status.                                        |
| Result          | select (string) | No       | clear or consider. Available values: Clear, Consider. |
| Adjudication    | string          | No       | Adjudication if any.                                  |
| Assessment      | string          | No       | Assess result if enabled.                             |
| Package         | string          | No       | Package.                                              |
| Candidate ID    | string          | Yes      | Candidate.                                            |
| Candidate email | string          | No       | Candidate email.                                      |
| Candidate name  | string          | No       | Candidate name.                                       |
| Completed at    | datetime        | No       | Completion time.                                      |
| Event ID        | string          | Yes      | Checkr event id, unique per delivery.                 |

**Outputs**

| Field           | Type     | Description                           |
| --------------- | -------- | ------------------------------------- |
| Report ID       | string   | Report id.                            |
| Status          | string   | Report status.                        |
| Result          | string   | clear or consider.                    |
| Adjudication    | string   | Adjudication if any.                  |
| Assessment      | string   | Assess result if enabled.             |
| Package         | string   | Package.                              |
| Candidate ID    | string   | Candidate.                            |
| Candidate email | string   | Candidate email.                      |
| Candidate name  | string   | Candidate name.                       |
| Completed at    | datetime | Completion time.                      |
| Event ID        | string   | Checkr event id, unique per delivery. |

#### Invitation Completed

Fires when a candidate finishes the Checkr-hosted consent flow and their report is ordered.

StackAI registers the Checkr webhook for you when you enable the trigger. The connection's API key must belong to the environment you selected on it, since Checkr signs every delivery with that key. Checkr allows only two webhook URLs per account across the Dashboard and the API, so remove an unused one in Account Settings > Developer Settings > Webhooks if registration fails. Deliveries arrive from a user agent starting with Checkr-Webhook/.

**Event inputs**

| Field           | Type     | Required | Description                       |
| --------------- | -------- | -------- | --------------------------------- |
| Invitation ID   | string   | Yes      | Invitation id.                    |
| Candidate ID    | string   | Yes      | Candidate.                        |
| Candidate email | string   | No       | Candidate email.                  |
| Candidate name  | string   | No       | Candidate name.                   |
| Package         | string   | Yes      | Package slug.                     |
| Report ID       | string   | No       | Report created by the completion. |
| Completed at    | datetime | No       | Completion time.                  |
| Event ID        | string   | Yes      | Checkr event id.                  |

**Outputs**

| Field           | Type     | Description                       |
| --------------- | -------- | --------------------------------- |
| Invitation ID   | string   | Invitation id.                    |
| Candidate ID    | string   | Candidate.                        |
| Candidate email | string   | Candidate email.                  |
| Candidate name  | string   | Candidate name.                   |
| Package         | string   | Package slug.                     |
| Report ID       | string   | Report created by the completion. |
| Completed at    | datetime | Completion time.                  |
| Event ID        | string   | Checkr event id.                  |

#### Adverse Action Notice Sent

Fires when Checkr sends a pre- or post-adverse action notice for a report, so compliance workflows can follow up.

Checkr itself sends these FCRA-regulated notices to the candidate, so the workflow reacts to a compliance step that already happened and never causes one. StackAI registers the Checkr webhook for you when the trigger is enabled. The connection's API key must be issued for the environment it selects, Checkr allows only two webhook URLs per account across the dashboard and the API, and deliveries arrive from a Checkr-Webhook/ user agent.

**Configuration**

| Field          | Type            | Required | Description                                                                                                       |
| -------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| Only for stage | select (string) | No       | Only fire for this notice stage. Empty fires for both. Available values: Pre-adverse action, Post-adverse action. |

**Event inputs**

| Field           | Type            | Required | Description                                                                                               |
| --------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| Stage           | select (string) | Yes      | pre\_adverse\_action or post\_adverse\_action. Available values: Pre-adverse action, Post-adverse action. |
| Report ID       | string          | Yes      | Report id.                                                                                                |
| Result          | string          | No       | Report result.                                                                                            |
| Adjudication    | string          | No       | Adjudication.                                                                                             |
| Package         | string          | No       | Package.                                                                                                  |
| Candidate ID    | string          | Yes      | Candidate.                                                                                                |
| Candidate email | string          | No       | Candidate email.                                                                                          |
| Candidate name  | string          | No       | Candidate name.                                                                                           |
| Occurred at     | datetime        | Yes      | When the notice was sent.                                                                                 |
| Event ID        | string          | Yes      | Checkr event id.                                                                                          |

**Outputs**

| Field           | Type     | Description                                    |
| --------------- | -------- | ---------------------------------------------- |
| Stage           | string   | pre\_adverse\_action or post\_adverse\_action. |
| Report ID       | string   | Report id.                                     |
| Result          | string   | Report result.                                 |
| Adjudication    | string   | Adjudication.                                  |
| Package         | string   | Package.                                       |
| Candidate ID    | string   | Candidate.                                     |
| Candidate email | string   | Candidate email.                               |
| Candidate name  | string   | Candidate name.                                |
| Occurred at     | datetime | When the notice was sent.                      |
| Event ID        | string   | Checkr event id.                               |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/checkr.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
