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.
  • Except for Sign-up & Connect embed: You have implemented Checkr OAuth if you are a partner.

To use a Checkr embed within your application

  1. Load Checkr's Web SDK directly through CDN. This ensures you always have the latest version.
  2. Add the embed to your frontend code.
  3. Except for Sign-up & Connect embed: Implement authentication for the embed using a SessionToken.
  4. Optionally, customize the embed based on your application's needs.

Load Checkr’s Web SDK

First, Load Checkr’s Web SDK using CDN

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

The Examples section below showcases some examples.

Add authentication

For Sign-up & Connect embed no previous authentication is required. In fact, Sign-up & Connect embed will implement most of the Checkr OAuth flow for you. It provides your application with an Oauth Authorization Code to exchange for an OAuth access token, which can be used by your application to make API calls to Checkr on behalf of your customers.

This Access Token must be used to request SessionTokens for authentication using other embeds.

Notes on keeping your Access Token secure

Be aware that the following token exchanges must take place within your own backend application to avoid exposing Access Tokens in your frontend application, which are considered sensitive secrets:

  1. Exchange of the Oauth Authorization Code for an Access Token
  2. Exchange of the Access Token for a Session Token (specific to use with embeds.)

Add authentication for other embeds

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.

Scopes are used to determine what access you are requesting for.

Scope Use case
order NewInvitation Embed, ReportsOverview Embed
disclosure Disclosure & Consent Embed

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

Use a Staging account to test Embeds

If you want to test with a Checkr Staging account, you can pass an additional param to any embed, env: "staging" to run the embeds against Staging. You can omit the env param entirely, or specify env: "production", to use a production account.

Note: Embeds do not support mixed Staging and Production usage on the same page - ensure all concurrently rendered embeds are using the same environment.

const embed = new Checkr.Embeds.SignUpFlow({
  env: 'staging'
  oauthTokenPath: '/your-backend/checkr-staging-oauth-token',
  partner: { id: 'abcdef1', name: 'Enterprise Partner Staging' },
});
<SignUpFlow
  env='staging'
  oauthTokenPath='/your-backend/checkr-staging-oauth-token'
  partner={{ id: 'abcdef1', name: 'Enterprise Partner Staging' }}
/>

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.

Sign-up & Connect Embed

Use the Sign-up & Connect embed to connect an existing Checkr account from an external application to Checkr and also create a Checkr account if needed.

This is the flow for Sign-up & Connect embed:

  1. Initial screen
    1. Select "Sign in with an existing Checkr account"
      1. Login to your Checkr account
      2. Get code for your application backend to retrieve access token.
      3. Back to your application
    2. Select "Create a new Checkr account"
      1. Get business information for Checkr account creation. Here are the business data required:
        1. First Name
        2. Last Name
        3. Business Email
        4. Business Name
        5. Business Address
        6. Business City (same city associated to US TAx ID)
        7. Business State
        8. Business Zipcode
        9. Business Phone Number
        10. USTaxID
      2. User selects and customize package
      3. Get payment information from the user. Here are the payment information required:
        1. In case of credit/debit card:
          1. Cardholder name
          2. Card Number
          3. Zipcode
          4. Expiration date
          5. Security Code
        2. In case of ACH/Bank Account:
          1. Account Type (personal/corporate)
          2. Name on Account
          3. Routing Number
          4. Account Number
          5. Confirm Account Number
      4. Get code for your application backend to retrieve access token
      5. Back to your application

Note that Sign-up & Connect Embed doesn’t handle customer account credentialing step.

Add the embed to your page

The Sign-up & Connect 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.SignUpFlow()
embed.render('#your-placeholder-div')
<SignUpFlow oauthTokenPath='/your-backend/checkr-oauth-token' partner={id: 'abcdef1', name: 'Enterprise Partner'}/>

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.SignUpFlow()
  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

Frontend Examples

const embed = new Checkr.Embeds.SignUpFlow({ oauthTokenPath: '/your-backend/oauth-tokens' })

Backend Requirement: endpoint to accept Oauth Authorization Code

You will need to implement a backend endpoint to accept the Oauth Authorization Code obtained upon completion of the signup flow.

The Embed utilizes the oauthTokenPath property to send the Oauth Authorization Code to your backend where it should be exchanged for an Access Token. This token is used to request a session token which can be used in other embeds.

The partner is required to possess both the client_id and client_secret, which can be located within the partner application data. This information is readily accessible for review via the Checkr dashboard and should live on your backend.

Example

An example implementation of the backend call in javascript would be:

import axios from "axios";

async function createOauthToken(body) {
  try {
    const response = await axios({
      method: "POST",
      url: `https://api.checkr.com/oauth/tokens`,
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      data: body,
    });

    return response.data;
  } catch (error) {
    throw error.response.errors;
  }
}

async function getOauthToken(req, context) {
  const { code } = await req.json();

  const body = {
    grant_type: "authorization_code",
    client_id: "<your_partner_app_client_id>",
    client_secret: "<your_partner_app_client_secret>",
    code: code,
  };

  const { access_token } = await createOauthToken(body);
  //Decide where & how you want save the oauth token
  await saveToken(access_token);

  res.status(200).json({ message: 'Token created successfully' });
}

The steps:

  1. Use code to call the ‘/oauth/tokens’ Checkr endpoint
  2. Save oauth token in your database or other secured storage for later use

Customize the embed

The Sign-up & Connect embed provides the following options to customize its default behavior.

Add preset values for Account Creation step

Use preset to specify a fixed value for an available input value. Preset inputs are displayed on the embed and it is available for users to edit it. Checkr provides 10 preset values for the Sign-up & Connect Embed:

  • presetFirstName
  • presetLastName
  • presetEmaill
  • presetBusinessName
  • presetAddress
  • presetCity
  • presetState
  • presetZipcode
  • presetPhoneNumber
  • presetUSTaxID
const embed = new Checkr.Embeds.SignUpFlow({
  oauthTokenPath:'/your-backend/checkr-oauth-token',
  partner:{id: 'abcdef1', name: 'Enterprise Partner'},
  presetName: 'John',
  presetLastName: 'Doe',
  presetEmail: 'johndoe@test.com',
  presetCity: 'San Francisco',
  presetPhone: '555-555-5555',
  presetTaxId: '123-45-6789',
  presetZipCode: '94103',
  presetBusinessName: 'Test Company',
  presetBusinessAddress: '123 Main St',
  presetState: 'CA',
  presetTaxId: '123-45-6789',
})
<SignUpFlow
  oauthTokenPath='/your-backend/checkr-oauth-token'
  partner={{id: 'abcdef1', name: 'Enterprise Partner'}}
  presetName='John'
  presetLastName='Doe'
  presetEmail='johndoe@test.com'
  presetCity='San Francisco'
  presetPhone='555-555-5555'
  presetTaxId='123-45-6789'
  presetZipCode='94103'
  presetBusinessName='Test Company'
  presetBusinessAddress='123 Main St'
  presetState='CA'
  presetTaxId='123-45-6789'
/>

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.SignUpFlow({
  oauthTokenPath: '/your-backend/checkr-oauth-token',
  partner: { id: 'abcdef1', name: 'Enterprise Partner' },
  signupLabel: 'This is a signup button label',
  signinLabel: 'This is a signin button label',
  emailLabel: 'This is an email label',
  emailPlaceholder: 'This is an email placeholder',
  nameLabel: 'This is a name label',
  namePlaceholder: 'This is a name placeholder',
  phoneLabel: 'This is a phone label',
  phonePlaceholder: 'This is a phone placeholder',
  lastNameLabel: 'This is a last name label',
  lastNamePlaceholder: 'This is a last name placeholder',
  passwordLabel: 'This is a password label',
  passwordPlaceholder: 'This is a password placeholder',
  confirmPasswordLabel: 'This is a confirm password label',
  confirmPasswordPlaceholder: 'This is a confirm password placeholder',
  businessNameLabel: 'This is a business name label',
  businessNamePlaceholder: 'This is a business name placeholder',
  businessAddressLabel: 'This is a business address label',
  businessAddressPlaceholder: 'This is a business address placeholder',
  cityLabel: 'This is a city label',
  cityPlaceholder: 'This is a city placeholder',
  zipCodeLabel: 'This is a zipcode label',
  zipCodePlaceholder: 'This is a zipcode placeholder',
  taxIdLabel: 'This is an US tax id label',
  taxIdPlaceholder: 'This is an US tax id placeholder',
  stateLabel: 'This is a state label',
  statePlaceholder: 'This is a state placeholder',
  packageButtonLabel: 'This is a package Next button label',
  paymentMethodLabel: 'This is a payment method label',
  paymentMethodPlaceholder: 'This is a payment method placeholder',
  cardHolderNameLabel: 'This is a card holder name label',
  cardHolderNamePlaceholder: 'This is a card holder name placeholder',
  cardNumberLabel: 'This is a card number label',
  cardNumberPlaceholder: 'This is a card number placeholder',
  expirationDateLabel: 'This is an expiration date label',
  expirationDatePlaceholder: 'This is an expiration date placeholder',
  securityCodeLabel: 'This is a security code label',
  securityCodePlaceholder: 'This is a security code placeholder',
  accountTypeLabel: 'This is an account type label',
  accountTypePlaceholder: 'This is an account type placeholder',
  nameOnAccountLabel: 'This is a name on account label',
  nameOnAccountPlaceholder: 'This is a name on account placeholder',
  routingNumberLabel: 'This is a routing number label',
  routingNumberPlaceholder: 'This is a routing number placeholder',
  accountNumberLabel: 'This is an account number label',
  accountNumberPlaceholder: 'This is an account number placeholder',
  confirmAccountNumberLabel: 'This is a confirm account number label',
  confirmAccountNumberPlaceholder: 'This is a confirm account number placeholder'
})
<SignUpFlow
  oauthTokenPath="/your-backend/checkr-oauth-token"
  partner={{id: 'abcdef1', name: 'Enterprise Partner'}}
  signupLabel="This is a signup label"
  signinLabel="This is a signin label"
  emailLabel="This is an email label"
  emailPlaceholder="This is an email placeholder"
  nameLabel="This is a name label"
  namePlaceholder="This is a name placeholder"
  phoneLabel="This is a phone label"
  phonePlaceholder="This is a phone placeholder"
  lastNameLabel="This is a last name label"
  lastNamePlaceholder="This is a last name placeholder"
  passwordLabel="This is a password label"
  passwordPlaceholder="This is a password placeholder"
  confirmPasswordLabel="This is a confirm password label"
  confirmPasswordPlaceholder="This is a confirm password placeholder"
  businessNameLabel="This is a business name label"
  businessNamePlaceholder="This is a business name placeholder"
  businessAddressLabel="This is a business address label"
  businessAddressPlaceholder="This is a business address placeholder"
  cityLabel="This is a city label"
  cityPlaceholder="This is a city placeholder"
  zipCodeLabel="This is a zipcode label"
  zipCodePlaceholder="This is a zipcode placeholder"
  taxIdLabel="This is an US tax id label"
  taxIdPlaceholder="This is an US tax id placeholder"
  stateLabel="This is a state label"
  statePlaceholder="This is a state placeholder"
  packageButtonLabel="This is a package Next button label"
  paymentMethodLabel="This is a payment method label"
  paymentMethodPlaceholder="This is a payment method placeholder"
  cardHolderNameLabel="This is a card holder name label"
  cardHolderNamePlaceholder="This is a card holder name placeholder"
  cardNumberLabel="This is a card number label"
  cardNumberPlaceholder="This is a card number placeholder"
  expirationDateLabel="This is an expiration date label"
  expirationDatePlaceholder="This is an expiration date placeholder"
  securityCodeLabel="This is a security code label"
  securityCodePlaceholder="This is a security code placeholder"
  accountTypeLabel="This is an account type label"
  accountTypePlaceholder="This is an account type placeholder"
  nameOnAccountLabel="This is a name on account label"
  nameOnAccountPlaceholder="This is a name on account placeholder"
  routingNumberLabel="This is a routing number label"
  routingNumberPlaceholder="This is a routing number placeholder"
  accountNumberLabel="This is an account number label"
  accountNumberPlaceholder="This is an account number placeholder"
  confirmAccountNumberLabel="This is a confirm account number label"
  confirmAccountNumberPlaceholder="This is a confirm account number placeholder"
/>

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 .step .rect1 .rect2
.btn-primary .checkbox-link .rect3 .rect4
.btn-submit .package-text .rect5
.btn-success .card
.form-control .card-title
.form-control-typeahead .card-selecte
.form-control-clear-typeahead .location
.form-group .info-text
.form-group-text .select-state
.form-group-typeahead .success-view
.form-label .typeahead-option-selected
.form-label-optional .typeahead-option
.form-label-typeahead .typeahead-options

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.SignUpFlow({ styles })

Define a custom theme

To define a custom theme from scratch, 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',
  },
  '.success-view': {
    color: '#fff',
  },
  '.typeahead-option-selected': {
    'background-color': '#87bbfd',
    color: '#fff',
  },
  '.typeahead-options': {
    'background-color': '#fff',
    'border-radius': '0.375rem',
  },
};

const embed = new Checkr.Embeds.SignUpFlow({ styles })
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',
  },
  '.success-view': {
    color: '#fff',
  },
  '.typeahead-option-selected': {
    'background-color': '#87bbfd',
    color: '#fff',
  },
  '.typeahead-options': {
    'background-color': '#fff',
    'border-radius': '0.375rem',
  },
};

<SignUpFlow styles={styles} />