Checkr partners with leading Staffing, On-Demand, Applicant Tracking Systems, and HR Systems to bring background checks to your customers. As a Checkr Partner, you can leverage the Checkr API to seamlessly connect your customers' Checkr accounts and integrate the background check process into your applications. Checkr's self-serve sign-up flow is fast, easy, and allows your customers to start running background checks within minutes after their account is credentialed. If you are interested in partnering with Checkr, submit this Checkr Partner Application form to connect with our Business Development team.

We provide industry standard and easy to follow API documentation of our RESTful APIs, OAuth, a staging account, and an average implementation timeline of 2 weeks from start to finish.

Building these integrations provides the following benefits:

• Generate new revenue streams: Checkr offers a revenue share program that can help partners accelerate their growth with little to no additional support.
• Attract and retain customers: Offering background checks differentiates platforms and increases stickiness. Customers are delighted by not having to navigate multiple systems with an all-in-one solution.
• Differentiate your brand: Checkr is the only background check company that enables businesses to start running background checks instantly.

Checkr provides a seamless customer self-serve sign-up flow, and automated customer account credentialing. In most cases, your customers will be able to start running background checks the same day they sign up for the account.

Checkr provides an automated candidate experience, which generates increased candidate engagement while decreasing required paperwork.

The Checkr-Hosted Apply Flow issues an email invitation to your candidates to enter their Personally Identifiable Information (PII), review disclosures and their summary of rights, and grant consent to the background check process. This process is optimized for viewing on desktop, tablet, and mobile devices.

The Checkr Candidate Portal allows candidates to log in to add their information, review reports, respond to queries for supporting documentation, and find answers to their questions.

Checkr's Candidate Portal helps you:

• Maintain compliance by having Checkr host the consent language and forms.
• Increase candidate engagement through automated follow-ups and reminders.
• Reduce candidate support requests through Checkr’s direct relationship to the candidate.

Throughout this document we will refer to “partners” and “customers”.

• Partners are our partner developers who are building an integration to Checkr from within their application.
• Customers are your end users (and ours), who use Checkr through your integration to order background checks.

This Getting Started guide will walk you through enabling your Checkr application, and allowing your customers to connect to it. Please see the Checkr API documentation for more information on our available APIs.

If you are new to the regulatory aspects of background screenings, please see the Checkr Help Center’s sections on Compliance, Adjudication and Review, and Checkr Screening Types.

For more information for your customers, including Checkr Dashboard User Guides, Getting Started with Checkr, and the background check process, see the User Guides in our Help Center.

As a partner of Checkr, you will be provided with both a Staging (test) account and a Production account. The Staging account is intended for your use when testing your partner integration with Checkr, while the Production account is for live, production use with your customers. The concepts and integration guidance provided in this document apply equally to both environments but there are a few key differences:

• API Base URL: Staging uses https://api.checkr-staging.com/ while Production uses https://api.checkr.com/
• Checkr Dashboard URL: Staging uses https://dashboard.checkrhq-staging.net/ while Production uses https://dashboard.checkr.com/

The first step to building a Checkr Partner integration is to set up your Checkr account with a “Partner Application”. Partner Applications allow you to connect your customers’ Checkr accounts to yours.

Create a New Partner Application from the Partner Dashboard at Management > Applications > Add.

To create this Partner Application, enter the following information:

• Application name: Your application’s name or brand. This name will be displayed in the Connect to Checkr flow.
• Application/Homepage URL: Your website URL. This will be used on our Partners page on the Checkr corporate site.
• Application description: A short description of your application. This will be used in Checkr Marketplace listings.
• Webhook URL: An endpoint to which webhooks will be transmitted. This endpoint will receive all webhook events transmitted for your connected customer accounts.
• Redirect URL: A page in your application to which your customers will be redirected after connecting their Checkr account using the Connect to Checkr flow. This URL must be HTTPS. It is used to secure your customers’ authentication and prevent Cross Site Request Forgery (CSRF) attacks.
• Logo: Your logo which is used in the Connect-to-Checkr flow.
• Your company color: The color you want to represent your brand.

Once you’ve created your Partner Application, Checkr will generate a client_id and a client_secret to use as your application credentials. These credentials allow you to generate an OAuth token in order to make API calls on behalf of connected customers. Keep them safe! (Particularly your client_secret: this is a secret key that should be stored securely in your application and not shared with anyone.)

Checkr customers often rely on Account Hierarchy for their workflows. Customers use their hierarchy to segment users' access, simplify selection of Packages at the time of order, and provide more granular detail on their monthly invoice.

When building your partner integration, use the Nodes resource to check whether your customers have defined an Account Hierarchy. This will future-proof your integration and ensure that all of your customers, both those who do and those who do not use Account Hierarchies, can use the same codebase.

Retrieve a customer's Account Hierarchy

$ curl -X GET /v1/nodes?page=1&per_page=25 -u {access_token}

Example response when Account Hierarchy is not enabled

{
   "error": "Sorry, your account is not enabled for segmentation"
}

Example response when Account Hierarchy is enabled but no nodes exist

{
   "data": [],
   "object": "list",
   "next_href": null,
   "previous_href": null,
   "count": 0
}

Example response when Account Hierarchy is enabled and nodes are defined

{
   "data": [
       {
           "custom_id": "ROOT_74407af0533e",
           "name": "Root",
           "tier": "Company",
           "parent_custom_id": null
       },
       {
           "custom_id": "CHLD_e7c3ab7bf4ad",
           "name": "Child 1",
           "tier": "Department",
           "parent_custom_id": "ROOT_74407af0533e",
       },
       {
           "custom_id": "CHLD_a106e1bfcfd2",
           "name": "Child 2",
           "tier": "Department",
           "parent_custom_id": "ROOT_74407af0533e",
       }
   ],
   "object": "list",
   "next_href": null,
   "previous_href": null,
   "count": 3
}

If no hierarchy exists (the error message "Sorry, your account is not enabled for segmentation" is returned) or an empty result is returned leave the node parameter blank for that customer when creating candidate invitations.

If a hierarchy is returned, a valid custom_id from the hierarchy results must be provided (as node) for invitations. Checkr provides several parameters on the GET /nodes endpoint to help you create a simple UI for selection (recommended) or to help automate the process without customer intervention (advanced).

Your customer's access_token must be used in the request. See Retrieve an access token for information on how to obtain a customer's access_token.

The Checkr-Hosted Signup flow automates account creation by collecting the information required to create Checkr accounts directly from your customers.

Your client_id is the unique identifier used to identify your Partner Application. Checkr uses this client_id to compose a unique link to embed in your application for your customers to use to either sign in to an existing Checkr account, or sign up for a new Checkr account.

With an active Partner Application and the "Signup flow" setting enabled, use the following links to point to your staging or production account.

Staging

• Create a new account: https://partners.checkrhq-staging.net/authorize/{client_id}/signup
• Connect an existing Checkr account to your application: https://partners.checkrhq-staging.net/authorize/{client_id}/signin
• Allow the customer to choose whether to create a new account or link an existing account: https://partners.checkrhq-staging.net/authorize/{client_id}

Production

• Create a new account: https://partners.checkr.com/authorize/{client_id}/signup
• Connect an existing Checkr account to your application: https://partners.checkr.com/authorize/{client_id}/signin
• Allow the customer to choose whether to create a new account or link an existing account: https://partners.checkr.com/authorize/{client_id}

If the “Signup flow” setting is disabled, the /signup URL will always redirect to /signin, and the “Need a Checkr account? Sign up” option will be hidden from the Sign In page.

The Sign In page with the “Signup flow” setting enabled vs. disabled

The Checkr-Hosted Signup flow

The Checkr-Hosted Signup flow is the simplest way for customers to create and connect a new Checkr account, and requires the least development effort on your part. Embed a “Connect to Checkr” link within your application and Checkr will collect the necessary user and company information to set up and credential the customer’s Checkr account.

Work with your Checkr Partner Manager to understand the best place within your application to embed this link for your customers.

Example "Connect to Checkr" link

https://partners.checkr.com/authorize/{client_id}?redirect_uri=https://partnerinc.com/checkr/callback&state=79a3ead9-2768-477f-8eca-724890dcf8d6

When embedding the “Connect to Checkr” link in your application, you may also elect to use the following URL parameters to pass additional information and secure your customers’ authentication.

• state (required): A string to be passed back as a URL parameter on redirect_uri upon flow completion. We recommend using state to pass through your unique ID of the customer so that you are aware which customer is connecting to your application.
• redirect_uri (optional): The URL to redirect your user to upon flow completion. This must match the configured redirect_uri in your Partner Application settings and must use the HTTPS protocol. This must be a static string. Wildcards (*) are not supported.

Following this link will direct a user to the Checkr-Hosted Signup flow. This flow consists of 3 steps and requires end users to supply information about themselves, their company, and the reason they are running background checks (also known as "permissible purpose"). Checkr accepts both credit/debit card and ACH information, which may be updated from your customer's Checkr Dashboard at any time. Customers are charged only for the background checks they run.

Note: When testing your "Connect to Checkr" implementation, be certain to use an email address which is not associated with the Checkr account hosting your applications. Attempting to sign up for a Checkr account with a user associated with that account will result in a 422 error.

Click here to access a live demo of the Checkr-Hosted Signup flow.

Checkr-Hosted Signup flow

Once your end user has completed the “Connect to Checkr” flow and successfully connected an account, they will be redirected to your defined redirect_uri with the state parameter you provided, and the code that you will use to request an access token. The access token grants your application the right to make API calls to Checkr on behalf of your customer.

For example:

https://partnerinc.com/checkr/callback?code={JWT}&state=79a3ead9-2768-477f-8eca-724890dcf8d6

Check that the state parameter string returned matches what you passed initially. If it doesn’t match or doesn’t exist, treat it as a failed connection, surface the error to the user, and redirect them to the start of the flow to try the process again.

Retrieve an access token

If the state string is a match to that initially passed, use the code parameter to call the Tokens endpoint and retrieve an access_token for your authorized customer. This is a one-time process and the access_token grants your application the right to make API calls to Checkr on behalf of the customer account.

Note: See Error codes for a list of 422 errors that may be returned for this call.

$ curl -X POST https://api.checkr.com/oauth/tokens \
    -d client_id={client_id} \
    -d client_secret={client_secret} \
    -d code={JWT}

Example response

{
    "access_token": "{access_token}", // customer's access token
    "scope": "read_write",
    "checkr_account_id": "5d78dfa52ea938723b2f2ba3" // customer's account ID
}

Note: The authorization code that is passed as a parameter on the redirect_uri is specifically used to retrieve an access token for the authorized customer. It can be used only once and expires 5 minutes after creation.

Access tokens are long-lived, account-level API keys that are not tied to specific user access. They are valid until revoked, so treat them with care. We recommend storing them encrypted in your application's data store along with the customer account ID (checkr_account_id) returned in the response payload.

Checkr-Hosted Sign In flow and existing Checkr customers

This process is available to customers who have an existing Checkr account, but are new to your partner integration. The Checkr-Hosted Sign In flow prompts users to sign into their existing Checkr account to authorize the connection. Only Checkr users with an Admin role within their Checkr account can perform this action.

Checkr-hosted Sign In and authorization flow

New accounts must be credentialed by Checkr’s Customer Success team before they will be allowed to request background checks. We use the information provided by the customer to assess the validity of the business and its permissible purpose. This process generally takes less than 1 business day.

Once the credentialing process is complete, Checkr will issue an account.credentialed webhook to the webhook_url configured during Partner Application setup. We will also notify your customer by email (the technical contact, if present, otherwise the first admin user).

If your customer's Checkr account is already credentialed, the account.credentialed webhook will be issued immediately after the Connect to Checkr flow is completed.

To check the account credentialing status for a customer account, use their access_token to call GET /v1/account. The account is credentialed if the authorized parameter is set to true.

Note: If your Partner Application has the "Pre-credentialed accounts" setting enabled, Checkr credentialing will not occur. Customer accounts created using your Connect to Checkr flow will receive an automatic credentialing upon account connection. This setting is available only for partners with a strict “Know Your Customer” (KYC) process, and can be enabled only by your Partner Manager.

After a customer has connected their Checkr account once, there is no need to perform the action again unless or until the customer's access token is deauthorized. We recommend displaying this connected state in your application to prevent your customers from attempting to create more than one Checkr account or connect more than once.

You may also elect to provide your end users the ability to disconnect their Checkr account from your application. Use the Deauthorize endpoint to deprecate a customer's access token. Customers may also deauthorize your application from the Checkr Dashboard. Listen for the token.deauthorized webhook for notification of these events.

Deauthorize a customer's access token

$ curl -X POST https://api.checkr.com/oauth/deauthorize -u {access_token}:

Example response

{
    "access_token": "{access_token}"
}

Once an access_token is deauthorized and the customer account is disconnected from your application, we recommend reflecting this state in your application so that customers can attempt to connect again.

Once your customer’s account is connected and has been credentialed, they may begin to order background checks from your application. A Package is a collection of Checkr Screenings, which may include criminal checks, motor vehicle records, or other background checks.

Packages may be selected for a candidate (select a Package for a candidate when ordering the background check), or for a job position (select a Package for a position, to be applied to all candidates placed against that position). Your use case will be dependent on workflows within your application.

For more information on screenings, see the Screening Types section of the Checkr Help Center.

Work with your Checkr Partner Manager to define the set of background check Packages and their pricing for your Partner account. Your connected customer accounts will inherit these Packages and prices by default. Your customers may also choose to configure their own packages in addition to these.

In some cases a connected customer account may have additional Packages configured that differ from those defined at the Partner account level. There may be accounts that already exist and are connected through the Sign In flow, or your customers may contact Checkr to add additional screening types required for their business. Because of this, we recommend using the customers' access_token to retrieve the Package list that will populate your Package selection interface, instead of relying on your partner account's Package list.

To order background checks for your customers using the POST /invitations call, you must know whether they are using account hierarchy to structure their account, and whether they are associating nodes within that hierarchy to their packages.

Use GET /nodes to determine whether your customer is using Account Hierarchy nodes and whether they have associated any packages to those nodes.

Retrieve a customer's Account Hierarchy nodes (if enabled) and any Package associations to those nodes

$ curl -X GET https://api.checkr.com/v1/nodes?include=packages -u {access_token}:

Example response

{
   "data": [
       {
           "custom_id": "ROOT_74407af0533e",
           "name": "Root",
       "packages": [
                "tasker_standard"
            ],
           "tier": "Company",
           "parent_custom_id": null
       },
       {
           "custom_id": "CHLD_e7c3ab7bf4ad",
           "name": "Child 1",
           "tier": "Department",
           "parent_custom_id": "ROOT_74407af0533e",
       },
       {
           "custom_id": "CHLD_a106e1bfcfd2",
           "name": "Child 2",
           "tier": "Department",
           "parent_custom_id": "ROOT_74407af0533e",
       }
   ],
   "object": "list",
   "next_href": null,
   "previous_href": null,
   "count": 3
}

Note: To display the packages returned from the GET /nodes?include=packages API call in your partner application, take the value(s) in the packages array, replace any underscores with spaces, and capitalize each word in the package name. (For example: Display "tasker_standard" as "Tasker Standard".)

The payload returned from the GET /nodes?include=packages call will determine what you need to do in your partner application:

• If the GET /nodes?include=packages API call returns any nodes, present a nodes drop-down and require the user to select the node they wish to associate to this background check invitation.
  • If the node selected by the customer has any packages associated to it, list ONLY those packages for selection
• In all other cases (if no nodes are returned, an error is returned, or nodes are returned but without any package associations), make a separate call to the GET /packages API endpoint call to retrieve all configured packages on the customer's account.

Retrieve a customer's package list

$ curl -X GET https://api.checkr.com/v1/packages -u {access_token}:

Example response

{
  "data": [
    {
      "id": "c6759e59e807618f8bcbd37a",
      "object": "package",
      "price": 2500,
      "apply_url": "https://apply.checkr.com/apply/customer-services-inc/532c20ea819b",
      "created_at": "2019-08-07T22:17:50Z",
      "deleted_at": null,
      "name": "Tasker Standard",
      "screenings": [
        {
          "type": "county_criminal_search",
          "subtype": "current"
        },
        {
          "type": "national_criminal_search",
          "subtype": "standard"
        },
        {
          "type": "sex_offender_search",
          "subtype": null
        },
        {
          "type": "ssn_trace",
          "subtype": null
        },
        {
          "type": "global_watchlist_search",
          "subtype": null
        }
      ],
      "slug": "tasker_standard",   // used for subsequent API calls
      "uri": "/v1/packages/c6759e59e807618f8bcbd37a"
    }
  ],
  "object": "list",
  "next_href": null,
  "previous_href": null,
  "count": 1
}

The response is paginated and contains 25 objects at a time. If the account contains more than 25 Packages, you will need to iterate through the paginated list or specify the per_page limit as described in the Pagination section of the API documentation. In this case, use the "name" field in the returned payload as the value to present for selection in your application.

You may also choose to cache the Package list and listen for each customer's package.* webhook events for updates. Checkr will transmit a webhook event for package.created, package.updated, and package.deleted. See the Webhooks section for more information on consuming Checkr webhooks.

To request a background check using the Checkr API, use the /invitations resource.

The POST /invitations call requires a Checkr Candidate ID. An existing candidate may be used, or a new candidate may be created before requesting a background check.

Using the /invitations resource supports all Checkr screening types and also automates the collection of candidate PII, and distribution of required disclosure and authorization forms.

To create an invitation, you must include the candidate ID for the background check. You may either retrieve this candidate ID for an existing candidate, or create a new candidate if one does not yet exist.

Checkr recommends re-using existing Checkr Candidate objects instead of creating a new one for each report, as it consolidates the candidate experience, and enables more seamless candidate support. It also ensure that Checkr's Analytics module presents more accurate data relating to candidates.

When creating a candidate, be certain to store the unique resource ID returned for that candidate against the representation of that candidate in your application. Use this ID for all subsequent invitations or report orders for that candidate.

Create a new Candidate

$ curl -X POST https://api.checkr.com/v1/candidates -u {access_token}:
      -d email=candidate@email.com

Example response

{
    "id": "e44aa283528e6fde7d542194",
    "object": "candidate",
    "email": "candidate@email.com",
    ...
}

If you do not know or have the Checkr Candidate ID, you can also use query parameters to retrieve a Candidate object by other identifiers. Typically we see this work well with the query parameters email (if you have this data) and/or custom_id (a string that you can use to store your application’s identifier against the Checkr candidate resource). For the full list of possible query parameters, see the List existing Candidates method.

Note: The returned object is a paginated list, as the call is not for a specific object but for a list of objects. See Retrieve an existing Candidate in the Checkr API documentation to retrieve a Candidate object by its ID.

Retrieve an existing Candidate

$ curl -X GET https://api.checkr.com/v1/candidates?email=candidate@email.com -u {access_token}:

Example response

{
  "data": [
    {
      "id": "e44aa283528e6fde7d542194",
      "object": "candidate",
      "email": "candidate@email.com",
      ...
    }
  ]
  "object": "list",
  "next_href": null,
  "previous_href": null,
  "count": 1
}

The easiest method to integrate background checks into your application is with the Checkr-Hosted Apply Flow. In this flow, use the Invitations resource to order the background check. Checkr sends an invitation email to the candidate to provide their information and consent, and once the invitation is completed a Report is automatically created. The invitation is valid for 7 days, in which Checkr will send a follow-up notice to the candidate to complete the invitation every 24 hours. If 7 days pass and the candidate has not yet completed the invitation, the invitation will expire and you must create a new invitation to proceed with the candidate.

Parameters required to Create an invitation:

• candidate_id: the ID of the candidate for whom the Invitation is created.
• package: the customer’s Package, selected when ordering the background check.
• node: the custom_id of the node associated with the background check.
• work_locations: an array of work locations, described using country, state, and city. (ISO-3166 alpha-2 format country code, two letter state code, and the name of the city)

package and work_locations are required to create an invitation. If the customer's account has nodes in Checkr, node is also required.

The work_location parameter is used by Checkr to determine compliance requirements for background check reports ordered through the Checkr Hosted Apply Flow. Checkr uses the candidate work location to apply the appropriate state- and city-based fair hiring laws, disclosures, and adverse action procedures. If a city is not provided, Checkr uses the state-based regulation.

Create an Invitation

$ curl -X POST https://api.checkr.com/v1/invitations -u {access_token}:
      -d candidate_id=e44aa283528e6fde7d542194 \
      -d package=tasker_standard \
      -d node=CHLD_e7c3ab7bf4ad \   // only if nodes exist on the account
      -d work_locations[][state]=CA \   // state required, city optional
      -d work_locations[][city]=San+Francisco

Example response

{
    "id": "551564b7865af96a28b13f36",
    "object": "invitation",
    "uri": "/v1/invitations/551564b7865af96a28b13f36",
    "invitation_url":
"https://apply.checkr.com/invite/try-checkr/290f9d6d6e46/test",
    "status": "pending",
    "created_at": "2015-05-14T17:45:34Z",
    "expires_at": "2015-05-21T17:45:34Z",
    "completed_at": null,
    "deleted_at": null,
    "package": "tasker_standard",
    "candidate_id": "e44aa283528e6fde7d542194",
    "report_id": null
    "tags": []
}

Note: If your integration calls for more control over your candidate communications, and a more consistent branding experience, Checkr provides an option to suppress the Checkr invitation email and reminders and still leverage the benefits of the Checkr-hosted Invitation flow. Work with your Checkr Partner Manager for more information and to enable this feature for your account.

Use the Checkr Candidate ID you have retrieved or created (see Creating or re-using Candidate objects), the Package “slug” (as selected in step Selecting Packages), and the candidate’s work location to create an Invitation.

Note: Checkr requires Candidates to provide only information that is required for the screenings contained in the Package (such as SSN for criminal screenings, driver license number and state for MVR). If you collect this information in your application, you may choose to pre-fill these fields in the invitation by creating or updating the Candidate object with this data prior to creating the Invitation. Any data collected must adhere to the validation referenced in our Checkr API documentation. By default, candidates may edit any information pre-populated in these fields during the invitation process.

Example: Checkr-Hosted Apply flow "Welcome" screen

Note: When using a Test API key or test access_token generated through a Test Partner Application, Checkr will not send an email to the test candidate email address. To access the invitation flow, retrieve the invitation_url from the Create Invitation response.

When the candidate completes the invitation, the Invitation status is updated to “completed” and the report_id value is updated with the created Report resource ID. Listen for the invitation.completed and report.created webhooks to receive notification of these events.

Report ETAs predict when County Criminal Checks will complete for each background check report. This ETA provides a date for the estimated completion of a specific report, helping both you and your candidates plan ahead. The process of searching at the county level varies from county to county. Some county searches are returned the same day, while some take several days or more, depending on the search methodology. While our predictions are highly accurate, they are not a guarantee. Estimates provided by Report ETA are correct within one business day for more than 9 out of 10 requested reports.

When the ETA is available, the report.updated webhook will be triggered and the estimated_completion_time field will have a datetime value populated. Subscribe and listen to this webhook event to access the Report's ETA for use within your application.

Retrieve a Report ETA

$ curl -X GET https://api.checkr.com/v1/reports/{report_id}/eta -u {access_token}:

Example response

{
  "estimate_generated_at": "2014-01-18T12:34:00Z",
  "estimated_completion_time": "2019-07-31T00:00:00Z"
}

Note: Report ETA is calculated only for Packages that include a County Criminal Check. If the Package does not include a Country Criminal Check, the endpoint will respond with a 404.

Once a report is created, it can take anywhere from a few hours to a few weeks for a background check to be completed. The average time to completion is 2–3 days, depending on the screenings included in the report.

Once a background check report is completed, Checkr will update the report with a status of “Clear”, “Consider”, or “Complete”. Please see What does the status of a report indicate in the Checkr Help Center to understand the types of statuses you may receive and how they are displayed in the Checkr Dashboard.

Between the time of report creation and report completion, some events may occur which require additional candidate input. For example, if exceptions occur, Checkr will request more information from the candidate to validate the accuracy of the information they’ve provided.

Once a report has been completed, you may choose to display some report information within your application.

Work with your legal team to determine how much consumer information to display from within your platform. Checkr suggests several options for our partners, to ensure you remain FCRA compliant, and do not become a CRA, including:

• Display nothing but a direct link to the report in the Checkr Dashboard. This option provides only access to the information, and does not display any information within the partner application itself.
• Display a direct link to the report in the Checkr Dashboard, and display the Checkr-provided status of the report and its ETA within your application. This provides slightly more audit information about the completion of the report, but does not supply any consumer report information within your application.
• Display invitation status within your application, in addition to the report status, ETA, and link to the report.

Retrieve the report status and link

$ curl -X GET https://api.checkr.com/v1/reports/{report_id} -u {access_token}:

Example response

{
      "id": "4722c07dd9a10c3985ae432a",
      "object": "report",
      "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
      "status": "clear",
      ...
}

To embed a direct link to the report in the Checkr Dashboard, trim “/v1/” from the uri and use the following in your application:

• If object is “test_report”, URL is https://dashboard.checkr.com/reports/{id}?test=true
• If object is “report”, URL is https://dashboard.checkr.com/reports/{i}

If any information contained on a candidate’s background check precludes them from working with your customer, it is your customer’s obligation to carry out the Adverse Action process. Although responsibility and liability for the Adverse Action process ultimately lies with your end user, Checkr helps make it easier to maintain a compliant Adverse Action process. We recommend directing your customers to the report in the Checkr Dashboard to adjudicate a report (Engage or Adverse Action).

To drive your customers to the Checkr Dashboard, provide a link to the candidate’s Report at https://dashboard.checkr.com/reports/{id}.

Any updates to the report as a result of the customer’s adjudication process can be received by your application in the form of webhooks. See the Webhooks section for more information on event types and typical workflows in which you might expect to receive them.

To ensure that your integration adheres to FCRA regulations and best practices, Checkr requires our partners to comply with a quick integration review. We will ask you to answer a few security questions and demonstrate your integration to one of our Partner Managers. You will be able to use your application in staging before receiving a production account. Live/production activity requires approval.

Download the Partner Certification Requirements PDF for a quick checklist of implementation components and functionality required for production approval. To assist in meeting certification requirements, Checkr also provides a Postman collection that partners can use during development. Download the Postman collection guide here.

1. Use the standard integration acceptance criteria as a guide to prepare for the demo. Make sure you can demonstrate the full checklist prior to scheduling your demo session.
2. Email us at partners@checkr.com to schedule an integration review once your development is complete and ready for production use.
3. We’ll ask you to demonstrate your completed integration through screenshare (using a Google Hangout) by walking us through Checkr account creation and connection, Package selection, background check ordering, and review of results. We will also review your Checkr integration as a whole to ensure proper functionality and to answer any questions that you may have. A review typically takes less than 30 minutes.

That's it! We’ll approve your integration (or make suggestions) when the review is complete.

This is the checklist you will be evaluated against to be approved for production use.

Checkr uses webhooks to communicate asynchronous changes on objects created with the API. Each time an event that you subscribed to occurs, Checkr submits a POST request to the webhook URL designated in your Partner Application with information about the event. For webhooks configured through Partner Applications, include_object is enabled by default, which means that the object referenced in the event will be returned as part of the payload.

Checkr supports the use of HTTPS as well as AWS Simple Notification System (SNS).

HTTPS

The endpoint must be public, and Live environment webhooks must be HTTPS. While we do accept HTTP in the Test environment, as a general rule of thumb we recommend using the HTTPS protocol. Checkr also supports (but does not require) the Basic Auth method of authentication by adding username:password@ in front of the hostname. These credentials must be URL escaped.

https://{user}:{password}@{hostname}/{path}

For example:

https://dw69ds8zg7yt:tmdghtwer999p2q3@partnerinc.com/webhooks/checkr

SNS

We also support webhook transmittal using Amazon SNS. To use SNS, your Access Key must have only the “Publish to SNS” IAM permission policy configured.

sns://{key_id}:{access_key}@{region}/{topic_owner}/{topic_name}

For example:

sns://AKI95AMUAD5K:a2n66fVKX7%2BYJKid3@us-east-1/12048/checkr

Your endpoint should respond to Checkr webhooks as quickly as possible. To acknowledge receipt of a webhook, your endpoint must return a 2xx HTTP status code. This status code should only indicate receipt of the message, not acknowledgment that it was successfully processed by your system. Any other information returned in the response headers or response body is ignored.

If a webhook is not successfully received for any reason, Checkr will continue trying to send it every minute for 10 minutes, then every hour for 24 hours. Webhooks failing for more than 7 consecutive days are automatically deleted.

We pass along a hash signature with each request in a header X-Checkr-Signature. The hash signature is generated with the HMAC algorithm, using your client_secret as a key and a SHA256 digest. When you receive a request, you can compute a hash and ensure that the one from Checkr matches.

Example hash signature computation:

printf "$compact_json" | openssl sha256 -hmac "$PARTNER_APP_CLIENT_SECRET"

In this example, $compact_json is the “non-pretty print” version of a JSON object. For example, you can get the compact version of a json file with the jq tool with: compact_json=$(jq -c < example_response.json).

Code examples on how to do this can be found here.

Note: The key used to compute the hash is your application's client secret, not an account-level API key or a customer's access token.

Any webhook event transmitted for an object requested using a customer's access_token will contain a signature in its header that can be verified using your client_secret.

Your Partner Application is subscribed to all webhook events by default, which include notifications for the resources Account, Candidates, Invitations, Verifications, Reports, Adverse Actions, and Packages. While the webhook event type is generally descriptive of how the object has been updated, we recommend consuming the object payload rather than relying on the event type itself. Each event describes the creation or update of its contained object, so it’s good practice to consume that payload as if you had made a call to retrieve the resource yourself.

While webhooks are helpful for updates, they are not foolproof. In some cases, report updates can be sent in rapid succession based on multiple events within the Checkr environment, and may be "mis-heard". There are some additional recommendations for guarding against duplicate and missed notifications in the API documentation.

The following table provides the most common sequence for the most common webhook events. This list is not exhaustive and does not describe all sequences. In any given cycle, some events may not occur, and others may occur in an order different than that listed here.

Most webhook events proceed in the following order.

Customers will see webhook logs for all events triggered from all partner applications which they use. Partners will see webhook logs for all events triggered by their customers' access token.

Use the Create Account API

If you collect the information included in the Checkr Hosted Signup flow on your customers’ behalf, use the Account endpoint to provide a more integrated, seamless experience. The Account endpoint can be used to create customer accounts without requiring the customer to complete a Checkr-hosted Signup flow.

The oauth_authorize parameter allows you to determine how your customer authorizes your application to connect to Checkr and order reports.

• By default, this parameter is set to false, which requires your customers to provide explicit authorization to your application to create candidates, invitations, and reports in Checkr on your customer’s behalf.

• If set to true, Checkr returns the authorization code in the account response. You may then use that access code in the oauth/token call to get an authorized token you can use to create reports/candidates in the customer's Checkr account.

Set oauth_authorize to false to create the account, then redirect your customers to the Checkr Hosted Sign In flow to sign in and explicitly grant authorization to your application. The authorization code will be returned as a URL parameter on your defined redirect_uri.

Note: If you send account information and set the oauth_authorize parameter to false, and then direct your customer to sign-in, their Checkr account will be created, but your customer will not be able to order reports.

For the Accounts and Tokens endpoints, authenticate using an API key generated through the Account Settings > Developer Settings page within the Checkr Dashboard. Logs generated from this API call can be accessed from the Logs tab in your Partner Checkr account.

Once the authorization code is acquired, use the Tokens endpoint to retrieve the customer’s access token.

Create an account that requires end-user authorization

$ curl -X POST https://api.checkr.com/v1/accounts -u {API_KEY}: \
    -d client_id={client_id} \
      -d false \
    -d See request body on [docs.checkr.com](https://docs.checkr.com/#operation/createAccount)

Example response

{
    "id": "dwe2u29j7gg47p8ed7wa",
    "object": "account",
    "name": "Customer Services Inc.",
    "default_compliance_state": "CA",
    "authorized": false,  // false means account is not yet credentialed
    "purpose": "employment",
    "user": {
        "email": "user@email.com",
        "full_name": "Jane Doe"
    },
    "company": {
        "industry": "72",
        "incorporation_state": "MA",
        "dba_name": "Customer Services",
        "website": "https://company.com",
        "tax_id": "123456789",
        "incorporation_type": "corporation",
        "street": "123 Main Street",
        "zipcode": "10200",
        "city": "Brooklyn",
        "state": "NY"
        "phone": "222-222-2222"
    }
    ...
}

Create an account that implies end-user authorization

$ curl -X POST https://api.checkr.com/v1/accounts \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d client_id=56269e3411a549fd07ed8d92 \
    -d name=Acme+Corporation \
    -d default_compliance_state=CA \
    -d purpose=employment \
    -d user[full_name]=Jeanette+Hughes \
    -d user[email]=user@example.com \
    -d company[dba_name]=Acme \
    -d company[industry]=72 \
    -d company[street]=123+Main+Street \
    -d company[city]=San Francisco \
    -d company[state]=CA \
    -d company[zipcode]=94107 \
    -d company[tax_id]=123456789 \
    -d company[incorporation_state]=CA \
    -d company[incorporation_type]=association \
    -d company[phone]=206-555-0100 \
    -d company[website]=https%3A%2F%2Fwww.example.com

Example response

{
  "id": "e44aa283528e6fde7d542194",
  "object": "account",
  "adverse_action_email": "john.doe@example.com",
  "api_authorized": true,
  "authorized": true,
  "available_screenings": [
    "county_civil_search",
    "county_criminal_search",
    "municipal_criminal_search",
    "employment_verification",
    "federal_civil_search",
    "federal_criminal_search",
    "motor_vehicle_report",
    "national_criminal_search",
    "sex_offender_search",
    "ssn_trace",
    "state_criminal_search"
  ],
  "billing_email": "john.doe@example.com",
  "company": {
    "name": "Acme Corporation",
    "dba_name": "ACME",
    "street": "123 Main St",
    "city": "Wilmington",
    "state": "DE",
    "zipcode": "19801",
    "phone": "206-555-0100",
    "website": "https://example.com",
    "industry": "52-59",
    "incorporation_state": "DE",
    "incorporation_type": "llc"
  },
  "compliance_contact_email": "compliance.team@example.com",
  "created_at": "2020-01-07T00:26:49Z",
  "default_compliance_city": "San Francisco",
  "default_compliance_state": "CA",
  "geos_required": false,
  "name": "Acme Corp",
  "purpose": "employment",
  "support_email": "support@example.com",
  "support_phone": "206-555-0188",
  "technical_contact_email": "jane.smith@example.com",
  "uri": "/v1/accounts/e44aa283528e6fde7d542194",
  "uri_name": "acme-corp"
}

If using the Account API to create customer accounts, you must also be able to pre-credential customer accounts for use with the POST /accounts call.

To pre-credential customer accounts, you must

• collect and store the information required to verify that the company is a legitimate business.
• collect and store the information required to verify that the use of the Checkr platform is for a permissible/employment purpose.
• collect and store the customer’s tax ID/EIN or state of incorporation.
• perform ongoing or annual verification that the customer’s company is legitimate and that they are using the platform for a permissible purpose.
• store the customer’s credentialing status for audit and recordkeeping purposes.

Note: If any required parameters are missing or cannot be validated from the `POST /accounts` call, Checkr will reject the account creation request. Please refer to the Accounts API documentation to review required fields.

For more information, see Get credentialed to run background checks in the Checkr Help Center, and Get Credentialed in the Checkr APIs.

A more advanced method to integrating background checks into your application is to use the Reports resource to build a custom, self-hosted flow. Once all required information is present on the Candidate resource, creating a Report will initiate the background check.

In this flow, you must collect and store both the candidate’s information and their consent within your application.

As an end user ordering consumer reports, your customers have certain responsibilities under the Fair Credit Reporting Act (FCRA). As your partner in background check screening, Checkr helps facilitate compliance with the FCRA in a few ways. Building a self-hosted Reports flow requires that you take on these obligations on behalf of your customers, including providing candidates the appropriate state- and city-specific disclosures for each screening type. For more information on your obligations under FCRA, and Checkr’s responsibilities as a Consumer Reporting Agency (CRA), check out our helpful Compliance resources in the Help Center, particularly our articles about obligations under FCRA and disclosures and authorizations.

You must also store your candidates’ consent to the background check, both to maintain proof that consent was granted, and to provide proof of consent for Checkr’s ongoing evaluation of partner compliance (annual compliance audits).

If you are interested in building a self-hosted Reports flow, work with your Checkr Partner Manager to understand the required disclosures and authorizations and PII that you must collect from the candidate before creating a report. Your Checkr Partner Manager must also review your workflow before you will be approved to use the Reports API in production.

Note: Some screening types are not supported with the Reports flow, such as credit checks and others that require significant data entry like employment and education verifications. For more information, see Reports in the Checkr API documentation.

In addition to providing a high-level report status (Pending, Clear, or Consider), you may also wish to expose the status of individual screenings within the Package. The most straightforward way to do this is to use the Embedded Resource feature. Use the include parameter to expand the screening objects in the Report resource in order to fetch the individual statuses.

Retrieve common screening statuses

$ curl -X GET https://api.checkr.com/v1/reports/{report_id}?include=ssn_trace,county_criminal_searches,global_watchlist_search,national_criminal_search,sex_offender_search,motor_vehicle_report -u {access_token}:

Note: See List existing Packages in the Checkr API documentation for a list of available screenings.

Example response

{
      "id": "4722c07dd9a10c3985ae432a",
      "object": "report",
      "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
      "status": "pending",  // overall report status
      "ssn_trace": {
          "id": "e44aa283528e6fde7d542194",
          "object": "ssn_trace",
          "uri": "/v1/ssn_traces/539fd88c101897f7cd000001",
          "status": "clear",  // ssn trace status
          ...
      },
      "county_criminal_searches": [
          {
            "id": "58845a3ea0fcd97136763136",
            "object": "county_criminal_search",
            "uri": "/v1/county_criminal_searches/58845a3ea0fcd97136763136",
            "status": "clear",  // county criminal search status
            ...
          },
          {
            "id": "58845a3ea0fcd97136763137",
            "object": "county_criminal_search",
            "uri": "/v1/county_criminal_searches/58845a3ea0fcd97136763137",
            "status": "pending",  // county criminal search status
            ...
          }
      ]
      ...
}

Some customers may use Checkr Assess to apply pre-adjudication rules to returned records. You may choose to surface these assessments when displaying these records within your application.

Use the Assessments endpoint to retrieve your customers’ applied assessments for reports.

Retrieve applied assessments

$ curl -X GET https://api.checkr.com/v1/reports/{report_id}/assessments \
    -u {access_token}:

Example response

{
  "data": [
    {
      "value": "eligible",
      "created_at": "2014-01-18T12:34:00Z",
      "ruleset": {
        "id": "e44aa283528e6fde7d542194",
        "name": "Ruleset for employees in Arizona",
        "version": {
          "number": 5
        }
      },
      "results": [
        {
          "value": "eligible",
          "assessed_objects": [
            {
              "object_id": "e44aa283528e6fde7d542194",
              "object_type": "criminal_charge"
            }
          ],
          "rule": {
            "name": "Allow dismissed charges rule",
            "type": "lookback_period"
          }
        }
      ]
    }
  ],
  "object": "list",
  "count": 1
}

Note: If your system supports its own account hierarchy, you may wish to sync your hierarchy with your customers' accounts on a regular cadence. For example, if your application has a node (such as a department or line of business), and you wish to create new nodes within your application using the /hierarchy endpoint, you may wish to keep hierarchies defined within your application in sync with those your customers have defined within their Checkr account.

This approach may present some significant challenges. Managing two separate account hierarchies (your application's and your customers') and keeping them in sync with one another requires careful planning. Be certain to work with your Checkr Partner Manager to determine if this approach is required for your integration.

For more information on using the hierarchy endpoint for syncing your hierarchy to your customers' Checkr accounts, see the Account Hierarchy in the Checkr API documentation.

Checkr provides an application demonstrating an end to end Checkr integration. It outlines best practices and patterns we see Checkr integrations adopt, and will help you develop a Checkr certified integration. Learn more about it here.

Most background checks using the Checkr Dashboard and the Checkr-Hosted Apply flow step through the following sequence of events:

1. Customer requests a report.
2. Candidate receives an email.
3. Candidate clicks the link in the email, enters their Personally Identifying Information (PII), and authorizes the search.
4. Report is processed.
5. Customer reviews the report in the Checkr Dashboard.
6. Customer decides to engage or adverse action the candidate.

For more information, see Understand the screening process in the Checkr API documentation.

The Checkr-Hosted Apply Flow, initiated by the POST /invitations call, automates PII and authorization collection from your candidates by presenting the following screens to them:

1. Welcome!: Checkr populates a screen with fields to collect the Personally Identifiable Information required for the requested screenings. Your candidate enters their information, and clicks Next.
2. Your Rights: Checkr presents your candidates with their rights under the FCRA, and asks that they acknowledge receipt. Your candidate clicks the "I agree" checkbox, and clicks Next.
3. Disclosures: Your candidate is presented with all hiring-specific disclosures, elects to receive a copy of their report, and acknowledges receipt.
4. Authorization: Candidate authorizes Checkr to proceed with their background check.

Once collected, Checkr stores your candidate's PII, their acknowledgement of receipt of the required authorizations and disclosures, and their consent to proceed with the background check.

Checkr-Hosted Apply Flow: API calls and webhooks

The following diagram shows the API calls used to initiate the Checkr-Hosted Apply Flow, and the webhooks issued during the workflow. This diagram also shows the most common flow and webhooks issued during report processing and completion.

Requesting and reviewing background checks requires users to view sensitive candidate data. While building your integration, please be aware that customers have assigned their users specific roles within the Checkr Dashboard, that may limit their access to view candidate data, including completed reports.

Checkr provides our customers with the following roles and permissions to assign their users:

• Limited User: Can view the Candidates list. Cannot see candidate or report details. This role is automatically assigned to all new users on an Account.
• User: Can view Reports. Assign this role to staff who provide candidates with updates on their background check.
• Requester: Can access, send, monitor, and cancel invitations to initiate background checks. This role can see the status of reports in the Candidates page, but cannot see the details or results of completed reports. This role can see candidate documents and exceptions, but cannot see completed report details. Assign this role to recruiters who initiate background checks.
• Adjudicator: Can see candidate and report details. This role can adjudicate Reports, engage candidates, and send Pre-Adverse Action notices to candidates. Assign this role to adjudication staff.
• Restricted Admin: Available for Account Hierarchy enabled accounts only, this role has all permissions of Adjudicators and Requesters for candidates in their Account Hierarchy node. This role can invite users to the account, and assign non-Admin user roles. This role can also view invoices and change developer settings. This role cannot update billing or settings. Assign this role to administrators for sub-nodes on your account.
• Admin: Has full access to all functionality within the Checkr Dashboard. This role can update account settings (including billing information), assign all roles to any users in the account. Limit this role to core members of your team.

Checkr's OAuth API offers a number of error codes to facilitate your building and troubleshooting. Some common error codes include:

POST '/oauth/tokens'

422 Unprocessable entity

• missing param(s)
• invalid code
• application not found
• user not found

Adjudication

The process by which customers reviewing returned background check reports decide whether to proceed with the candidate’s hiring/engagement process. The adjudication process ends with either candidate engagement or candidate adverse action.

Adverse Action

The process by which a customer, upon reviewing the results of the background check, informs the candidate that they may not move forward with the hiring process. When notifying candidates of this preliminary decision, customers must follow applicable Federal, State, and local laws. For employment purpose checks: including providing information on how to dispute any incorrect or outdated information in the report, before moving forward with or terminating the hiring process. Steps related to this process include:

• Pre-Adverse Action: Process by which employer/platform notifies the candidate of their preliminary adverse engagement decision. This includes written notification to the candidate that the Adverse Action process has been initiated, provides the candidate with a copy of their background check and other applicable notices, and gives the candidate the opportunity to address any potential inaccuracies in their background check before the final engagement decision is made. Pre-Adverse Action applies only to employment purpose background checks, including independent contractor relationships.
• Post-Adverse Action: Process by which the employer/platform notifies the candidate of their final adverse engagement decision. This notification completes the Adverse Action process and is conducted after a minimum of 7 calendar days from the dispatch of the Pre-Adverse Action notice.

Candidate Experience

Checkr’s Candidate Experience team interacts directly with candidates. The team manages incoming phone calls, emails, and portal communications from candidates work to answer their questions and issues relating to their background check.

Candidate

The individual on whom a background check is run. Sometimes also referred to as the applicant.

Certification

The process by which customers certify to Checkr that proper consent (that is, disclosure and authorization) to run the requested background check has been obtained from the candidate and their use of background reports complies with all applicable laws. Certification occurs at the time of report request whether through API or manual orders in the Checkr dashboard.

Credentialing

The process by which checkr confirms the validity of the business and its permissible purpose. New accounts must be credentialed by Checkr’s Customer Success team before they will be allowed to request background checks.

Customer

The person or company ordering a background check.

Disposition

The court’s determination regarding the outcome or status of a criminal charge. A criminal case contains one or more charges, and each individual charge contains its own disposition. For example: Charge 1: conviction; Charge 2: Dismissed.

Dispute

Action of a candidate informing Checkr that there is information on their report that is potentially inaccurate, incomplete, or unreportable.

Engage

To hire a candidate.

Exceptions

Issued when a Report cannot be completed as initially run, exceptions usually require additional documents or information from the candidate to be resolved.

Invitations

To initiate the Checkr Hosted Apply flow, Checkr issues email “invitations” to candidates to participate in the background check process. These invitations link to an automated flow which collects the required candidate Personally Identifiable Information (PII), presents relevant authorizations and disclosures, and asks the candidate to consent to the background check.

Package

A defined group of screenings, offered as a set.

Partner

A company with whom Checkr works to provide software and services to customers.

Partner application

The application partner developers must configure within their Checkr account to obtain their Checkr Client ID, configure webhook URIs, and manage their interface with the Checkr APIs.

Personally Identifiable Information (PII)

Any information that can be used to identify a specific individual, such as name, social security number, date of birth, or mother‘s maiden name. PII can be sensitive or non-sensitive. Sensitive PII is information which, when disclosed, could result in harm to the individual whose privacy has been breached. Non-sensitive PII can be gathered from public records, phone books, corporate directories, and websites.

Screening

A specific background check search Checkr offers customers.