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.
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.
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.
While authentication is processing, the embed displays a loading state in your app. Then, the embed fetches and renders the returned data.
When the requested data is returned, the embed renders within your application.
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}` })}/>
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.
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' />
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
}'
Checkr will respond with a SessionToken.
{
"token": "example-session-token"
}
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.
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:
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.
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 />
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 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' />
Request callbacks are triggered when sending an invitation to a candidate is successful or fails.
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
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"
]
}
}
The NewInvitation embed provides the following options to customize its default behavior.
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' />
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"/>
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:
presetWorkLocation
can be used to preset two different scenarios
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'} />
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'} />
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' />
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}/>
Use standard CSS to customize the look and feel of your embeds.
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.
Embeds include a default theme, and allow users to both customize this default theme or build a custom theme from scratch.
useBaseline
option.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-control-clear-typeahead | .success-view | ||
.form-group | .typeahead-option-selected | ||
.form-group-email | .typeahead-option | ||
.form-group-typeahead | .typeahead-options | ||
.form-label | .work-location | ||
.form-label-typeahead |
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 })
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} />
Use the ReportsOverview embed to show the progress and result of a background check for a candidate. The embed displays:
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.
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.
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' />
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 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' />
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. |
Use standard CSS to customize the look and feel of your embeds.
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.
Embeds include a default theme, and allow users to both customize this default theme or build a custom theme from scratch.
useBaseline
option.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 |
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 })
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} />
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
can be used to be pass a nonce to all inline style
elements rendered by Embeds.
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} />
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} />
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. |
Contact Checkr to enable Account Hierarchy for your account | 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. |
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 |
---|
Examples using fakeMode on Codepen |
Fullstack example on CodeSandbox |
A complete reference integration showing OAuth and Embeds on Github |
Embed patterns app showing various UX patterns to incorporate Embeds |
Additions and updates to the Checkr embeds. Versioning follows the SemVer specification.
CSP security fix for modal styles
Added sessionTokenRequestHeaders
to enable sending headers to an application's backend endpoint. See authentication flow for more details.
sessionTokenRequestHeaders
to enable sending headers to an application's backend endpoint. See authentication flow for more details.enableLogging
option to enable client side logging. See the troubleshooting section for more details.