Checkr Web SDK (v1)

Overview

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.

Getting Started

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.

Install Checkr’s Web SDK

First, install Checkr’s Web SDK using CDN, NPM, or 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.

Add authentication

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.

Session Token Authentication

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.

  1. The embed uses Checkr APIs to request data.
  2. 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.

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}` })}/>
Note: Do not use a public endpoint for the sessionTokenPath property. Be certain to complete your application's user authentication and authorization before responding to the request.

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.

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:

Use the following as the request JSON payload:

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.

Use fakeMode to preview Embeds

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.

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

Webhooks

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.

NewInvitation Embed

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.

Add the embed to your page

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.

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 />

Add the embed as a modal

Use JavaScript to launch the Embed as a modal, for example on the click of a button in your application.

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

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

The default modal width is 600px on desktops and 100% on mobile devices. Use width option to change the desktop width.

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

Add authentication

Add SessionToken based on the authentication section above. For example:

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

Add request callbacks

Request callbacks are triggered when sending an invitation to a candidate is successful or fails.

onInvitationSuccess

onInvitationSuccess is triggered when an invitation is successfully sent to a candidate. Use this callback to capture details like the Checkr Invitation or Candidate id in your system.

const handleOnInvitationSuccess = (response) => { console.log(response) }
const embed = new Checkr.Embeds.NewInvitation({onInvitationSuccess: handleOnInvitationSuccess})
const handleOnInvitationSuccess = (response) => { console.log(response) }
<NewInvitation onInvitationSuccess={handleOnInvitationSuccess}/>
{
  "candidate_id": "00f3d4c23b83e2b845ffd991",
  "created_at": "2021-09-28T03:41:30.722Z",
  "external_job_application_id": null,
  "id": "bd6b0537212189fd6a4fa2db",
  "invitation_id": "73a5d217bd981e885841b589",
  "external_system": "web-sdk",
  "external_background_check_id": null,
  "external_candidate_id": null,
  "external_requester_id": null,
  "report_id": "e44aa283528e6fde7d542194",
  "uri": "/background_checks/bd6b0537212189fd6a4fa2db",
  "candidate_url": "https://dashboard.checkr.com/candidates/00f3d4c23b83e2b845ffd991",
  "report_url": "https://dashboard.checkr.com/reports/e44aa283528e6fde7d542194"
}

onInvitationError

onInvitationError is triggered when sending an invitation fails. By default, these errors are displayed at the top of the rendered embed within your application. The NewInvitation embed will return all errors generated by the Checkr API.

const handleOnInvitationError = (response) => { console.log(response) }
const embed = new Checkr.Embeds.NewInvitation({onInvitationError: handleOnInvitationError})
const handleOnInvitationError = (response) => { console.log(response) }
<NewInvitation onInvitationError={handleOnInvitationError}/>
{
  "errors": {
    "invitation": [
        "Package not found"
    ]
  }
}

Customize the embed

The NewInvitation embed provides the following options to customize its default behavior.

Define a custom Candidate ID

You may define a custom candidate ID using the NewInvitation embed to reference Checkr candidates and their background checks. This will create a Checkr candidate with its custom_id set to the specified external candidate ID.

You may use this custom ID to map Checkr candidate IDs to objects in your product. You may also use this custom candidate ID as an argument to the ReportsOverview embed, to show all reports for the candidate.

const embed = new Checkr.Embeds.NewInvitation({ externalCandidateId : 'your-candidate-id' })
<NewInvitation externalCandidateId='your-candidate-id' />

Add a default candidate email address

Checkr allows you to set a default value for the NewInvitations embed's email address. This value will appear in the Embed when launched, and may be modified by your users.

const embed = new Checkr.Embeds.NewInvitation({ defaultEmail: "john@doe.com" })
<NewInvitation defaultEmail="john@doe.com"/>

Add preset values

Use preset to specify a fixed value for an available input value. Preset inputs (except email) are not displayed on the embed.

Checkr provides 4 preset values for the NewInvitation Embed:

  • presetEmail
  • presetNodeCustomId
  • presetPackageSlug
  • presetWorkLocation

presetWorkLocation can be used to preset two different scenarios

  • The full work location
const embed = new Checkr.Embeds.NewInvitation({
  presetEmail: 'john@doe.com',
  presetNodeCustomId: '1000002',
  presetPackageSlug: 'criminal_drug',
  presetWorkLocation: {country: 'US', state: 'CA', city: 'Los Angeles'}
})
<NewInvitation
  presetEmail='john@doe.com'
  presetNodeCustomId='1000002'
  presetPackageSlug='criminal_drug'
  presetWorkLocation={country: 'US', state: 'CA', city: 'Los Angeles'} />
  • Only the country
const embed = new Checkr.Embeds.NewInvitation({
  presetEmail: 'john@doe.com',
  presetNodeCustomId: '1000002',
  presetPackageSlug: 'criminal_drug',
  presetWorkLocation: {country: 'US'}
})
<NewInvitation
  presetEmail='john@doe.com'
  presetNodeCustomId='1000002'
  presetPackageSlug='criminal_drug'
  presetWorkLocation={country: 'US'} />

Define labels and placeholders

Checkr allows you to customize the embed’s label and placeholder text for customer input fields.

const embed = new Checkr.Embeds.NewInvitation({
  cityLabel: 'This is a city label',
  cityPlaceholder: 'This is a city placeholder',
  countryLabel: 'This is a country label',
  countryPlaceholder: 'This is a country placeholder',
  emailLabel: 'This is an email label',
  emailPlaceholder: 'This is an email placeholder',
  nodeLabel: 'This is a node label',
  nodePlaceholder: 'This is a node placeholder',
  packageLabel: 'This is a package label',
  packagePlaceholder: 'This is a package placeholder',
  stateLabel: 'This is a state label',
  statePlaceholder: 'This is a state placeholder'
})
<NewInvitation
  cityLabel='This is a city label'
  cityPlaceholder='This is a city placeholder'
  countryLabel= 'This is a country label'
  countryPlaceholder= 'This is a country placeholder'
  emailLabel='This is an email label'
  emailPlaceholder='This is an email placeholder'
  nodeLabel='This is a node label'
  nodePlaceholder='This is a node placeholder'
  packageLabel='This is a package label'
  packagePlaceholder='This is a package placeholder'
  stateLabel='This is a state label'
  statePlaceholder='This is a state placeholder' />

Define filters

You may define filters to limit the packages and nodes displayed to your customers within the Embed.

Filters may be defined based on the parameters included with the package and node resources within the Checkr API.

This example filters on the node’s name, the package’s slug, and also the work location country. The embed will display only nodes with names including central, only packages including basic or premium in their slug, and only Canada or the US as selectable countries.

const embed = new Checkr.Embeds.NewInvitation({
  nodeFilter: allNodes =>
    allNodes.filter(node => node.name.toLowerCase().includes('central')),
  packageFilter: allPackages =>
    allPackages.filter(pkg => ['basic', 'premium'].includes(pkg.slug.toLowerCase())),
  workLocationCountryFilter: allCountries =>
    allCountries.filter(country => ['US', 'CA'].includes(country.code))
})
const nodeFilter = allNodes => allNodes.filter(node => node.name.toLowerCase().includes('central'))
const packageFilter =  allPackages => allPackages.filter(pkg => ['basic', 'premium'].includes(pkg.slug.toLowerCase()))
const workLocationCountryFilter = allCountries => allCountries.filter(country => ['US', 'CA'].includes(country.code)

<NewInvitation nodeFilter={nodeFilter} packageFilter={packageFilter} workLocationCountryFilter={workLocationCountryFilter}/>

Style the embed

Use standard CSS to customize the look and feel of your embeds.

Adjust the width on the page

By default, Embeds are rendered using the full width of their container div. Adjust the width of the container div on your page to control the width of the embed.

Customize the theme

Embeds include a default theme, and allow users to both customize this default theme or build a custom theme from scratch.

  • To customize the default theme, specify the styles you wish to override.
  • To build a theme from scratch, use the useBaseline option.
Note: An embed's styles neither inherit nor conflict with your site's styles. Embed UIs are complex, have a specific structure, and therefore have specific styling needs. Inheriting an external page's styling will break the embed.

The following classes may be targeted by CSS.

Embed CSS selectors Loading CSS selectors
.btn .header .checkr-embeds-loading-container .loading-bar
.btn-loading .new-invitation .rect1 .rect2
.btn-primary .select-city .rect3 .rect4
.btn-submit .select-country .rect5
.btn-success .select-node
.form-control .select-package
.form-control-typeahead .select-state
.form-group .success-view
.form-group-email .typeahead-option-selected
.form-group-typeahead .typeahead-options
.form-label .work-location
.form-label-typeahead .work-location

Edit the default theme

To edit the default theme, specify new values for any of the default CSS selectors listed above.

const styles = {
  '.btn-primary': {
    background: '#0a8080',
  },
  '.header': {
    'font-size': '150%',
    'font-weight': 'bold',
    color: '#F45D48',
  },
  '.form-label': {
    'font-weight': '700',
  },
  '.form-control': {
    background: '#F3FAFB',
    padding: '0.5rem',
  },
  '.form-control:focus, .form-control:focus-visible': {
    'border-color': '#0a8080',
  },
};

const embed = new Checkr.Embeds.NewInvitation({ styles })

Define a custom theme

To define a custom theme from stratch, set useBaseline to true, then specify values for any of the selectors listed below. If values are not set for a selector, the embed will render without styles for that value.

const styles = {
  useBaseline: true,
  '.btn': {
    'border-radius': '0.375rem',
    color: '#ffffff',
  },
  '.btn-primary': {
    'background-color': '#fcd669',
  },
  '.btn-submit': {
    display: 'block',
    width: '100%',
  },
  '.btn-submit:disabled': {
    opacity: 0.7,
  },
  '.form-control': {
    'background-color': '#7795f8',
    border: '0',
    color: '#fff',
    padding: '0.5rem',
    width: 'calc(100% - 1rem)',
  },
  '.form-control::placeholder': {
    color: '#87bbfd',
  },
  '.form-control-container': {
    display: 'inline-block',
    position: 'relative',
    width: '70%',
  },
  '.form-label': {
    color: '#c4f0ff',
    display: 'inline-block',
    padding: '0.5rem 1rem',
    'text-overflow': 'ellipsis',
    'white-space': 'nowrap',
    width: '30%',
  },
  '.form-group': {
    'background-color': '#7795f8',
    'border-radius': '0.375rem',
    'box-shadow':
      '0 6px 9px rgb(50 50 93 / 6%), 0 2px 5px rgb(0 0 0 / 8%), inset 0 1px 0 #829fff',
    'margin-bottom': '1.5rem',
  },
  '.header': {
    display: 'none',
  },
  '.new-invitation': {
    'background-color': '#6772e5',
    'border-radius': '0.375rem',
    padding: '1.8rem 2rem',
  },
  '.success-view': {
    color: '#fff',
  },
  '.typeahead-option-selected': {
    'background-color': '#87bbfd',
    color: '#fff',
  },
  '.typeahead-options': {
    'background-color': '#fff',
    'border-radius': '0.375rem',
  },
};

<NewInvitation styles={styles} />

ReportsOverview Embed

Use the ReportsOverview embed to show the progress and result of a background check for a candidate. The embed displays:

  • the name of the package ordered,
  • the status of the invitation to the candidate,
  • the status of the report's progress and its ETA, and
  • the result of the report and its completion timestamp.

The ReportsOverview embed also provides a link to the candidate in the Checkr Dashboard if the invitation has not yet been completed, and a link to the report once it has been initiated.

Add the embed to your page

The ReportsOverview 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. The embed requires a Checkr candidate ID or an external candidate ID (the externalCandidateId property) as an argument.

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.

const embed = new Checkr.Embeds.ReportsOverview({ externalCandidateId: 'wd-ba1hdmbaav' })
<ReportsOverview externalCandidateId='wd-ba1hdmbaav' />

Add the embed as a modal

Use JavaScript to launch the Embed as a modal, for example on the click of a button in your application.

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

btn.addEventListener('click', event => {
  const embed = new Checkr.Embeds.ReportsOverview({ candidateId: '4c262214ab5daabbd1a6basc' })
  embed.modal()
})

The default modal width is 600px on desktops and 100% on mobile devices. Use width property to change the default desktop width.

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

Add authentication

Add SessionToken based on the authentication section above. For example:

const embed = new Checkr.Embeds.ReportsOverview({ sessionTokenPath: '/your-backend/session-tokens', externalCandidateId: 'wd-ba1hdmbaav' })
<ReportsOverview sessionTokenPath='/your-backend/checkr-session-tokens' externalCandidateId='wd-ba1hdmbaav' />

Status Display

The ReportsOverview embed will display the following status and results descriptions.

Status Description
Invitation Sent The Checkr invitation has been sent.
Invitation Expired The candidate did not complete the Checkr invitation within 7 days of its creation.
Invitation Canceled The invitation was canceled from the Dashboard or API.
Report Pending The report is in progress.
Report Suspended An exception has not been resolved within 7 days (or two attempts), and the report has been placed in Suspended status.
Clear The background check report was completed with a Clear result value.
Clear with canceled screenings A suspended or pending report was force completed, which cancelled some screenings. The completed screenings were all clear.
Did Not Pass No dispute was initiated by the candidate within the required 7 days after a pre-adverse action was initiated by the customer.
Report Canceled The report was cancelled from the Dashboard or API.

Style the embed

Use standard CSS to customize the look and feel of your embeds.

Adjust the width on the page

By default, Embeds are rendered using the full width of their container div. Adjust the width of the container div on your page to control the width of the embed.

Customize the theme

Embeds include a default theme, and allow users to both customize this default theme or build a custom theme from scratch.

  • To customize the default theme, specify the styles you wish to override.
  • To build a theme from scratch, use the useBaseline option.
Note: An embed's styles neither inherit nor conflict with your site's styles. Embed UIs are complex, have a specific structure, and therefore have specific styling needs. Inheriting an external page's styling will break the embed.

The following classes may be targeted by CSS.

Embed CSS selectors Loading CSS selectors
.reports-overview .row-content .checkr-embed-loading-container .loading-bar
.bgc-item .bgc-status-container .rect1 .rect2
.bgc-package-name .bgc-status-text .rect3 .rect4
.bgc-time-description .bgc-dashboard-link .rect5

Edit the default theme

To edit the default theme, specify new values for any of the default CSS selectors listed above.

const styles = {
  '.reports-overview': {
    padding: '5px',
  },
  '.bgc-item': {
    border: 'none',
    'border-radius': '5px',
    'box-shadow': '0px 2px 5px rgb(0 0 0 / 15%)',
  },
  '.bgc-package-name': {
    'font-size': '150%',
    'font-weight': 'bold',
    color: '#F45D48',
  },
  '.bgc-status-container': {
    'background-color': 'white',
  },
  '.bgc-status-text': {
    'font-size': '100%',
    color: 'black',
  },
  '.bgc-dashboard-link': {
    'background-color': '#0a8080',
    padding: '5px 8px 5px 8px',
    'font-size': '14px',
    color: 'white',
    'text-decoration': 'none',
    'border-radius': '3px',
  },
  '.bgc-dashboard-link:hover': {
    opacity: '.9',
    cursor: 'pointer',
  },
};

const embed = new Checkr.Embeds.ReportsOverview({ styles })

Define a custom theme

To define a custom theme from stratch, set useBaseline to true, then specify values for any of the selectors listed below. If values are not set for a selector, the embed will render without styles for that value.

const styles = {
  useBaseline: true,
  '.reports-overview': {
    'border-radius': '0.375rem',
    'background-color': '#6772e5',
    padding: '0.6rem 0.6rem',
  },
  '.bgc-item': {
    'background-color': '#7795f8',
    border: 'none',
    'border-radius': '5px',
    'box-shadow': '0px 2px 5px rgb(0 0 0 / 15%)',
    padding: '15px',
  },
  '.bgc-package-name': {
    'font-size': '130%',
    'font-weight': 'bold',
    color: 'white',
  },
  '.bgc-status-text': {
    'font-size': '100%',
    'font-weight': 500,
    color: 'white',
  },
  '.bgc-time-description': {
    color: '#87bbfd',
  },
  '.bgc-dashboard-link': {
    'background-color': '#fcd669',
    padding: '5px 8px 5px 8px',
    'font-size': '14px',
    'text-decoration': 'none',
    'border-radius': '3px',
    color: 'black',
  },
  '.bgc-dashboard-link:hover': {
    opacity: '.9',
    cursor: 'pointer',
  },
}

<ReportsOverview styles={styles} />

Content Security Policy

Embeds rely on style and script elements rendered inside the iframe. If your application uses a Content Security Policy, these elements might be blocked by your rules. To avoid this, permit the following sources in your policy. If you are installing the Checkr WebSDK library via CDN, additionally add the CDN source to the script-src header.

CSP Header Sources
frame-src https://web-sdk-services.checkr.com
script-src https://web-sdk-services.checkr.com https://cdn.jsdelivr.net/npm/@checkr/web-sdk

cspNonce

cspNonce can be used to be pass a nonce to all inline style elements rendered by Embeds.

Note: Nonces should be generated differently each time the page loads and should be a random base64-encoded string of at least 128 bits of data from a cryptographically secure random number generator. If your site uses static html, consider using a CSP hash instead.
const crypto = require('crypto')
const cspNonce = crypto.randomBytes(16).toString('base64') // '8IBTHwOdqNKAWeKl7plt8g=='

const embed = new Checkr.Embeds.NewInvitation({ cspNonce })
const crypto = require('crypto')
const cspNonce = crypto.randomBytes(16).toString('base64') // '8IBTHwOdqNKAWeKl7plt8g=='

<NewInvitation cspNonce={cspNonce} />

Troubleshooting

API requests made by the Embed appear on the API logs page in the Checkr Dashboard. Candidate invitations and reports can be viewed in the Checkr Dashboard. You can filter by the Checkr candidate or the external candidate ID. Use the enableLogging argument in any embed to see requests made in the browser using Chrome developer tools.

const embed = new Checkr.Embeds.NewInvitation({ enableLogging: true })
<NewInvitation enableLogging={true} />

Common error messages

All validation errors returned by Checkr APIs calls are shown on the embed’s UI. Use the API logs in the Checkr Dashboard (and other general tactics) to understand which API calls are failing.

The embed also includes an error message specific to the embed:

Error Message Reasons
This account has not been approved for use The POST web_sdk/session_tokens request has failed because the account is not credentialed to send Invitations.
Sorry, your account is not enabled for segmentation The GET /nodes request has failed because the account does not have Account Hierarchy enabled.
Could not load Account data The SessionToken cannot be acquired. API logs will show the POST /web_sdk/session_tokens request failing.
The GET /packages or GET /nodes requests have failed due to bad authentication.
Note: When an embed loads for the first time, it sends an HTTP POST request to your backend, requesting a SessionToken. To surface any errors that may occur from this request on the embed's UI, send the status and data from the error response.
router.post("/session-tokens", async (req, res, next) => {
  const authenticated = authenticateUser();

  if (authenticated) {
    try {
      const response = await axios({
        headers: { "Content-Type": "application/json" },
        method: "POST",
        url: `${apiHost}/web_sdk/session_tokens`,
        auth: {
          username: oAuthAccessToken,
          password: ""
        },
        data: {
          scopes: ["order"]
        }
      });

      res.send(response.data);
    } catch ({ response: { status, data } }) {
      // Send over error data to surface errors from the Checkr API to the Embeds UI
      res.status(status).send(data);
    }
  } else {
    res.sendStatus(401);
  }
});

Examples

Click to see a few examples using fake mode on Codepen.

You may also review a full stack example on CodeSandbox. Plug your OAuth Access Token to use it.

The Checkr embed patterns app shows the various workflows in which embeds can be adopted in your product.

Changelog

Additions and updates to the Checkr embeds. Versioning follows the SemVer specification.

June 14, 2022

version 0.0.26

  • Added sessionTokenRequestHeaders to enable sending headers to an application's backend endpoint. See authentication flow for more details.

March 19, 2022

version 0.0.23

  • Add the ReportsOverview embed

October 19, 2021

version 0.0.3

September 20, 2021

version 0.0.2

  • Update dependencies.
  • Add README.

September 22, 2021

version 0.0.1

  • Initial Embed release.