Checkr Embeds are the fastest way to add background check experiences to a product using pre-built components that you can add with a few lines of code. Our goal is to make it easy to build an end-to-end background check experience within your product, which will be automatically updated with new Checkr releases. Checkr embeds are fully themeable.

Checkr embeds are built using the Checkr WebSDK library, and can be added to your application using JavaScript or React (>= v16). Embeds are supported by Microsoft Edge, Chrome, and Firefox versions released on or after 2019.

Checkr embeds may be used by both developers building directly to the Checkr API, and by partner developers building partner applications.

View Example

Pre-requisites

• You already have an account with Checkr.
• You have implemented Checkr OAuth if you are a partner.

To use a Checkr embed within your application

1. Install Checkr's Web SDK using NPM or Yarn, or load it directly through CDN.
2. Add the embed to your frontend code.
3. Implement authentication for the embed using a SessionToken.
4. Optionally, customize the embed based on your application's needs.

First, install Checkr’s Web SDK using CDN, NPM, or Yarn.

• CDN
• NPM
• YARN

<script src="https://cdn.jsdelivr.net/npm/@checkr/web-sdk/dist/web-sdk.umd.js"></script>

npm install --save @checkr/web-sdk

yarn add @checkr/web-sdk

The Examples section below showcases some examples.

Checkr embeds follow a typical lifecycle, first authenticating, then fetching and rendering returned data. Checkr embeds authenticate using SessionTokens. SessionTokens are short-lived and have narrowly scoped access. API Keys and OAuth Access Tokens cannot be used directly to authenticate a Checkr embed.

First, the embed authenticates with Checkr.

1. The embed sends a request from your application's frontend to your application's backend for a Checkr SessionToken.
2. Your application’s backend must first authenticate the logged in user using its own mechanisms, and then pass the request to Checkr.
3. Checkr sends a SessionToken to your backend in response.
4. Your application’s backend then passes the SessionToken to the embed running on your application's frontend.

While authentication is processing, the embed displays a loading state in your app. Then, the embed fetches and renders the returned data.

5. The embed uses Checkr APIs to request data.
6. Checkr APIs return the requested data directly to the embed.

When the requested data is returned, the embed renders within your application.

Embed authentication flow

When an Embed loads for the first time, it sends an HTTP POST request to your backend, requesting a SessionToken. Use the sessionTokenPath property to set your application's backend endpoint to use.

By default, your application's cookies are sent to your backend to help you authenticate the user. To enable authentication via headers (such as bearer tokens), use the sessionTokenRequestHeaders property as shown below.

• JavaScript
• React

const embed = new Checkr.Embeds.NewInvitation({ sessionTokenPath: '/your-backend/session-tokens', sessionTokenRequestHeaders: () => ({ Authorization : `Bearer ${token}` }))

<NewInvitation sessionTokenPath='/your-backend/checkr-session-tokens' sessionTokenRequestHeaders={() => ({ Authorization : `Bearer ${token}` })}/>

Run your application's user authentication and authorization rules before requesting Checkr to acquire a SessionToken.

Step 1: The embed requests a SessionToken from your backend

The embed will use the sessionTokenPath property to request a SessionToken from your backend.

• JavaScript
• React

const embed = new Checkr.Embeds.NewInvitation({ sessionTokenPath: '/your-backend/session-tokens' })

<NewInvitation sessionTokenPath='/your-backend/checkr-session-tokens' />

Step 2: Send a request for a SessionToken from your backend to Checkr

Checkr provides two means to acquire this SessionToken: one for our direct customers, and one for our partner developers.

• Customers building directly to the Checkr APIs: Use the API Keys found in the Checkr Dashboard to request SessionTokens.

• Partner developers, building partner applications: Use the OAuth Access Token acquired through Checkr OAuth to request SessionTokens. This is a pre-requisite for using Embeds. See the Checkr Partner Guides for more information.

When your application’s backend receives the HTTP Post request from the embed, run authentication and authorization rules based on your application logic (for the current user), and then make the following call to Checkr.

POST {checkr-api-host}/web_sdk/session_tokens

Checkr API host:

• Staging: https://api.checkr-staging.com/v1
• Production: https://api.checkr.com/v1

Use the following as the request JSON payload:

• Partner Request
• Direct Customer Request

curl --request POST \
  --url {checkr-api-host}/web_sdk/session_tokens \
  --user your-checkr-oauth-access-token: \
  --header 'Content-Type: application/json' \
  --data '{
    "scopes": ["order"]
}'

curl --request POST \
  --url {checkr-api-host}/web_sdk/session_tokens \
  --user your-checkr-api-key: \
  --header 'Content-Type: application/json' \
  --data '{
    "scopes": ["order"],
    "direct": true
}'

Step 3: Checkr responds to your backend with a SessionToken

Checkr will respond with a SessionToken.

{
  "token": "example-session-token"
}

Step 4: Return the acquired SessionToken from your backend to your frontend

Return the JSON response (from above) from the Checkr API back to your frontend.

SessionTokens are short-lived. If they expire, the embed will automatically attempt to renew them by re-executing Steps 2 to 4.

Fake mode lets you play with the Embed without it making any API calls. When fakeMode is enabled in an embed (all embeds support it), the embed would work using canned data.

• JavaScript
• React

const embed = new Checkr.Embeds.NewInvitation({ fakeMode: true })

<NewInvitation fakeMode={true} />

While Embeds do not rely on Webhooks, you can definitely use it in combination with Embeds to build more advanced features such as workflow automation in your product.

Use the NewInvitation embed to invite candidates to the Checkr-Hosted Apply Flow.

The following data is captured from the user of this Embed:

• Checkr allows businesses to model their organization as a tree of nodes. A node selector is shown if the account is configured with more than one node.
• The employment work location. Work location defines where your candidate will be employed.
• The package to be used for the background check. Packages are a list of screenings to be run for a report.
• The email address used to invite the candidate to the background check.

The NewInvitation embed may be added to your page either inline or as a modal. Adding the embed inline will render the embed on your application's page. Adding it as a modal allows you to launch the embed from a button or other feature on your page.

Add the embed inline

Both JavaScript and React may be used to insert the Embed inline in your application. The results shown below are examples of the Embed's default appearance.

• JavaScript
• React
• Result

const embed = new Checkr.Embeds.NewInvitation()
embed.render('#your-placeholder-div')

import {Embeds} from '@checkr/web-sdk'
const NewInvitation = Embeds.NewInvitation.useReact(React, ReactDOM)

return <NewInvitation />

const btn = document.getElementById('your-button')

btn.addEventListener('click', event => {
  const embed = new Checkr.Embeds.NewInvitation()
  embed.modal()
})

embed.modal({ width: '700px' })