Checkr is a modern, RESTful API-driven background screening service. The Checkr API uses resource-oriented URLs, supports HTTPS authentication and HTTPS verbs, and leverages JSON in all responses passed back to customers.

Checkr is used by over 10,000 customers in a wide variety of industries, and supports a range of screening products and candidate workflows. For a full list of our screenings, please see the Checkr Screenings section below or read the Checkr Help Center articles on Screening Types.

This Programming Guide is designed to help customers get up-and-running with Checkr's background screening services, both by providing the necessary context to understand the background screening industry and its regulations, and by giving technical guidance on how to work with the Checkr API.

Note: The cURL command is used for all examples in the Checkr API documentation.

Other resources

For a complete set of User Guides for the Checkr Dashboard, and more information on the compliance and regulatory aspects of background screenings, please see the Checkr Help Center.

For a more targeted set of Checkr Dashboard learning paths for talent sourcing roles like Recruiters, Adjudicators, or Program Administrators, please see the Checkr Learning Center.

Checkr follows a standardized screening process:

1. Customer requests a background check.
2. Candidate is presented with and signs the necessary disclosures and authorizations, and submits the requested Personally Identifiable Information (PII).
   • With the Checkr-Hosted Apply Flow, the candidate signs disclosures and authorizations and enters their own PII.
   • With a custom self-hosted flow, the Checkr customer collects the required authorizations, and passes Checkr candidate PII using the Checkr API.
3. Checkr conducts an SSN Trace, and collects associated addresses.
4. Checkr runs searches or verifications based on the screening Packages requested.
5. Checkr applies appropriate compliance filters based on the customer’s settings and candidate’s provided residence to determine which records to show, and returns a finalized report to the customer.
6. If there is a record on the report, the customer Engages or Adverse Actions the Candidate, based on an individualized assessment of the candidate's report.

1. Request a background check

To initiate a background check, a customer provides Checkr their candidate's email address (for a Checkr-Hosted Apply Flow) or the candidate's PII (for a self-hosted flow). For more information on ways to achieve this, please see Designing your workflow.

2. Candidate signs disclosures and authorizations

Under the U.S. Fair Credit Reporting Act (FCRA), customers are obligated to collect consent from their candidates when running background checks through Checkr or any other Consumer Reporting Agency (CRA).

The Checkr-Hosted Apply Flow presents candidates with fields in which the requested PII may be entered, and collects candidate information on behalf of the customer. Checkr will also present disclosures and authorizations to the candidate, and enable eSignature to capture consent, on behalf of customers using this flow with the Checkr Dashboard or email invitation flow.

Custom self-hosted flows collect candidate PII, and pass the information to Checkr using the Checkr API. Customers creating a self-hosted flow will receive guidance from the Checkr team on setting up a similar process as required.

3. Checkr runs an SSN Trace

Checkr runs an SSN Trace to match the candidate’s provided PII with existing credit header data mapped to the SSN. This process yields a list of names and addresses associated with the entered SSN, which can be used to supplement the background check process.

At this point Checkr also conducts some initial data comparisons to check that critical pieces of information, like a candidate's submitted Date of Birth (DOB) and SSN, align with information held on file by the credit bureaus. If there is information that looks out of place, Checkr may reach out directly to the candidate, through their email address, to gain further confirmation or data from the individual.

Once the candidate's information has been confirmed and an address history developed, the background check screening process begins.

4. Checkr runs the requested Screenings

Checkr then runs the customer's requested Screenings. Based on the results of the SSN Trace, Checkr may expand the search for the requested Screenings to include counties where the candidate may have lived in the past.

5. Completed Report is returned

Once a report has been completed, customers receive a report result update of Clear or Consider through their selected method of API webhooks, email, or Checkr Dashboard notifications.

Clear and Consider are the default results. A Clear result can be interpreted as that report having no items listed on the candidate’s record that require consideration. A report with a result of Consider indicates that there are items on the candidate’s report that require your review. With both Clear and Consider reports, customers must decide whether or not to engage a candidate. Checkr does not make this determination on the customer’s behalf.

6. Customer evaluates the Report

After the Report is completed and returned, the customer must evaluate the report, and make a final hiring determination. In maintaining a process compliant with per FCRA legislation and EEOC guidelines, Checkr does not make this determination on the customer's behalf.

Before gaining a Checkr staging or production account, you must first work with a Checkr Account Executive or Customer Success representative to create and credential your account.

Credentialing and authorizing your account

The background screening industry in the United States is heavily regulated by federal, state, and local levels of government, and primarily by the Fair Credit Reporting Act (FCRA). Checkr complies with these laws, and helps its customers comply, through multiple Checkr product features.

Two key processes in the account authorization process also enable compliance: establishing permissible purpose, and confirming a compliant user interface workflow.

Establishing permissible purpose

One of the main provisions of FCRA is the requirement to establish a legitimate "permissible purpose" for running a background screen on an individual. These permissible purposes include running background screens for employment purposes (that is, making hiring decisions), making a decision to extend credit to an individual, or for what the law calls a "legitimate business purpose".

Checkr establishes a customer's permissible purpose by collecting and confirming a number of key details about the business entity running a background screen, including:

• Legal business name (associated with Employer Identification Number)
• State of incorporation
• Articles of incorporation
• Employer Identification Number

Some permissible purposes may impose additional legal requirements on the business entity running a background screen. For example, purposes involving checking a candidate's credit history require an onsite inspection of the entity's business premises.

Confirming a compliant user interface (UI) workflow

When building a candidate user experience that includes the capture of information necessary to run a background check, there are a number of essential components that must be included to send a compliant request to Checkr. For more information on these requirements and best practices, please see Building your candidate experience.

Before a Checkr account is credentialed and authorized for production API access, the Checkr Customer Success team confirms that your UI/UX flow meets our requirements and that all necessary information is being appropriately captured. More details about these requirements are included below and throughout the Checkr customer account onboarding process.

Checkr authenticates your API requests using your account's API keys. If you do not include your key when making an API request, Checkr will return an authentication error.

Go to Account Settings > Developer Settings in the Checkr Dashboard to create both Secret and Publishable keys for your account. Use the Secret Key within your staging and production environments.

Resources like Candidates, Reports, and Packages will not transfer from your Staging environment to your Live environment. For more information, please see Requesting a Staging Account in Getting Started.

There are two types of API keys: secret and publishable.

• Secret API keys should be kept confidential and stored only on your own servers. Your account's secret API key can perform any API request to Checkr without restriction.
• Publishable API keys are for use only with Checkr's JS API, and are meant solely to identify your account with Checkr. They aren't secret, and can therefore safely be published in your site's JavaScript code, or in an Android or iPhone app.

Using your API keys

Once your Checkr account has been created, your API keys will be available in the Checkr Dashboard, in the Account Settings > Developer Settings page.

Note: To prevent unexpected charges for production background checks, do not use your production Publishable API key for testing or development.

Keeping your keys safe

Access to your API keys should be granted only to those that need them. Your secret API key can be used to make any API call on behalf of your account, such as creating Candidates, requesting and upgrading Screenings, and creating Geos. Your publishable API key can only create Candidates in the Checkr system, and may be used to publish app or site builds.

To further protect your keys, ensure that they are not included in any version control system that you may be using.

Expiring keys

If an API key is compromised, expire the key in the Checkr Dashboard to block it. Click Expire key to set an expiration date for the selected key, and Create new key to create a new one to replace it.

Checkr's API is flexible enough to support a range of workflows for integrating background screening into your candidate onboarding process. At a high-level there are three options, each with unique benefits and disadvantages.

Checkr Dashboard experience

The Checkr Dashboard allows customers to initiate a background check through either the Checkr-Hosted Apply Flow or through a Manual flow.

• Selecting Invite Candidates allows customers to enter an email address for their candidates. Checkr will then issue an invitation to the selected candidate which includes a Checkr-provided link. Clicking the link launches the Checkr-Hosted Apply Flow, which will walk them through the next steps in the process.

• Selecting Manual Order requires customers to enter their candidate's PII, and confirm that they have collected the necessary authorizations on their candidate's behalf.

For more information, see Order a Report in the Checkr Help Center.

Checkr-hosted candidate experience

The Checkr-hosted candidate experience enables Checkr customers to easily set up a modern, compliant candidate background screening process in their onboarding flow with limited development effort. The Checkr-hosted candidate experience has the full set of features and functionality of the Checkr product, and is built on top of the Checkr API, making it an easy and powerful option for customers looking to begin using Checkr as quickly as possible.

The Checkr-Hosted Apply Flow, by which invitations are issued to candidates to participate in their background check, forms the basis of the Checkr-hosted candidate experience. Use the Invitations resource to build this automated process into your application.

The Checkr-hosted experience can be initiated in two ways:

Candidate invitations triggered by API: Customers can choose to build a programmatic trigger into their site or product to order reports and send candidates invitations to participate in the background check process. In this case, a customer passes Checkr a candidate email address through the API, which triggers an email to that address to collect the candidate's information and present the necessary compliance forms and disclosures. This option requires developer time to build a Checkr backend integration into the customer's product, but does present benefits for automation and programmatic ordering.

Candidate invitations triggered through the Checkr Dashboard: Customers can log into the Checkr Dashboard and issue an invitation to participate in the background check process to a candidate's email address. This option requires no developer time to build any Checkr integration, but lacks any automation or programmatic ordering, making it difficult to scale for high volume environments.

Customers may also use the Checkr Dashboard to submit a Manual Order. Selecting this option requires them to collect the candidate’s authorization and consent to a background screening “offline”. This means that the customer will collect the candidate’s Personally Identifiable Information (PII), present the necessary authorizations and disclosures, and collect and store necessary signatures through separate means. Customers must then submit their candidate's PII to Checkr through the Checkr Dashboard, and certify that proper consent was obtained from their candidate.

Note: When using candidate invitations and the Checkr-Hosted Apply Flow, understand that Checkr is facilitating your obligations with regard to applicable consumer reporting laws. Before using either method of candidate invitations, you should fully review the template copies of disclosure(s) and authorization language to ensure your business needs are met.

Self-hosted candidate experience

The self-hosted candidate experience enables Checkr customers to completely control the user onboarding experience, from the look and feel of the candidate's UX, to the specific API calls made during the process, to the flexibility in timing and ordering of those calls. Some unique Checkr functionality, like programmatic report upgrades, are also available only to those customers hosting their own candidate experience.

While the self-hosted flow offers more control over the background check experience, this needs to be weighed against the burden of having to be responsible for maintaining compliance when presenting the background check disclosure and consent forms, which is not a trivial undertaking. Typically, the self-hosted flow works best for our larger customers that have a dedicated legal department that can provide ongoing monitoring of the changing compliance landscape for background checks. Please see the Creating a fully custom apply flow section for more detail on this.

Building your candidate experience

To help customers meet the regulatory demands of the background screening industry, Checkr has defined the following UX requirements for customers building their own candidate onboarding experience:

• Collect candidate PII: Collect candidate Personally Identifiable Information (PII), with additional requirements around the data captured and its formatting. This screen may be presented and the information collected at any point in the signup flow
• Present consumer rights summary, and collect acknowledgement: Present a summary of consumer rights under the Fair Credit Reporting Act (FCRA) and candidate’s acknowledgement of receipt. This screen may be presented on the same page as the collection of PII.
• Present disclosures and collect acknowledgement: Present a disclosure form and candidate’s acknowledgement of receipt. This disclosure form MUST be on its own page with no extraneous information.
• Present state-specific disclosures and collect acknowledgement (if necessary): Present any state-specific disclosure forms and candidate’s acknowledgement of receipt. For example: California requires its own disclosure separate from the general background check disclosure. Washington State DMV requires a release of liability for accessing Motor Vehicle Records for employment.
• Present authorization form and collect consent: Present an authorization form and collection of consent to a background screening. Present a signature of authorization form, compliant with the ESIGN Act.
• Upload authorization: upload authorization to Checkr using the Documents endpoint https://api.checkr.com/v1/candidates/{candidate_id}/documents with the type of "consent"

Checkr can provide you with copy templates for each of these documents. Checkr routinely has these documents reviewed for general compliance and best practice in the industry, but you should always consult your own legal counsel when using templates and ensure they work for your business. Please work with your Checkr Account Executive or Customer Success Manager to receive Checkr’s set of templates. These templates, the documents they include, and other requirements will be explained throughout the Checkr customer account onboarding process.

Note: Requirements differ for customers running background screening programs limited to running a Motor Vehicle Record (MVR) on candidates for a non-employment or contractor purpose. The requirements for running an MVR in order to provide a service such as a car or scooter rental are far less onerous than the requirements for other uses of the MVR, and require only one or two screens of necessary consent and disclosure. Please contact your Checkr Account Executive or Customer Success Manager if you'd like to learn more about these streamlined requirements.

Compliance and eSignature

Collecting proof of authorization from your candidates is one of your most important responsibilities before performing a background screen through Checkr or any other Consumer Reporting Agency. Under the FCRA, Checkr cannot provide you with a report unless you certify that you have obtained proper authorization. Maintaining proof of this process is essential in the event that either you or Checkr is audited, or a candidate threatens you with litigation.

Checkr recommends two means of collecting and storing this eSignature during the consent and authorization flow:

• Store generated PDFs
  • Identify the candidate by username and password
  • Have the candidate type their name in a signature box
  • Upon submission of authorization, generate a PDF of the authorization form, including the date, time, and IP address
• Store data to generate PDF on demand
  • Enable on-demand generation of PDFs
  • Identify the candidate by username and password
  • Have the candidate type their name in signature box
  • Upon submission of authorization, store the date, timestamp, IP address, and signed name
  • Have the ability to reproduce a PDF copy of the authorization form on demand, including the date and timestamp, IP address, and signed name

The Checkr Dashboard allows Checkr customers to begin using the Checkr platform immediately and with no developer effort. The Checkr Dashboard includes the full feature and functionality set as the Checkr API interface, with a few key limitations.

For more information, please see the Checkr Dashboard User Guide in the Checkr Help Center.

The following sections will walk you through the steps necessary to get started running background checks with the Checkr API:

• Get credentialed
• Request a Staging Account
• Get your API key
• Authenticate with Checkr
• Create a Candidate
• Create an Invitation
• Retrieve the Report
• Parse the results

Before gaining access to the Checkr APIs and Dashboard, you must be properly credentialed to request background checks. Work with your Customer Support Representative to provide the required documentation, and complete the credentialing process.

For more information, see Getting credentialed above.

Checkr provides customers with the option of a “staging account” that can be used to test your integration and use the Checkr Dashboard prior to deploying your integration to your production account. The staging account can be set up to match the settings from your production account and allows for submission of background check orders without incurring any billable events. To accomplish this, Checkr uses candidate “mocked” data setups that result in predefined background check results, mimicking the most common outcomes you will encounter in your production account.

Once your staging account has been created, Checkr will provide you with a document containing this mocked candidate data.

Request a staging account

Use our Submit a request form to request a staging account. Enter the following information:

1. How can we help?: select "I need assistance configuring my account", then select "Other".

2. Topic: enter "Staging account setup request"

3. Description: Please enter the following information:

   • Admin user for staging: Provide the email address to be used as the initial Admin account for this requested staging account.

   • Checkr production Admin: Provide the email address for one of the Admin users of your Checkr Dashboard account.

New staging accounts are typically created within 1-2 business days of a submitted request.

Configure your staging account

Upon successful creation of the staging account, the email address specified in the staging account request submission will receive an email from Checkr providing a temporary password to the account and allowing the recipient to create a permanent password. This initial user will have an Admin user role which allows them to invite other users to the account as they see fit.

Once you have Admin access to the staging account, go to Account Settings > Developer Settings. On this page, in the “API keys” section click Create Key and choose Secret. Use the resulting API key to authenticate all of your API calls to this staging account.

To enable webhooks for the account, from the Account Settings > Developer Settings page scroll down to New Webhook. Enter a URL and click Add to create a new webhook. You may also use this page to select the webhook notifications you wish to receive from Checkr.

The staging account’s API calls, responses, and webhooks follow the same pattern and response structure as those of the production environment.

Note: The staging account uses the API host URL: https://api.checkr-staging.com/v1 for all calls.

Testing Checkr's functions and features

To facilitate building with the Checkr API, Checkr staging accounts support a number of mocked candidate profiles that will return predictable results. This allows you to test a number of different report outcomes and other workflows before moving your integration to your production account. To ensure the desired outcome, you must enter the candidate data exactly as provided in this mocked candidate data document or the resulting report will remain in pending status indefinitely.

Reports created in the staging account will typically complete within minutes of submission, though this can vary depending upon the relative load on the staging environment servers.

Note: Checkr’s product and development teams also use the staging environment to test new functionality. It is therefore possible that one or more of the mocked candidate records may not return the expected results. If you encounter unexpected returns for a mock data candidate, please test a different candidate from the mocked data document with a similar predefined outcome. If the problem persists, reach out to your Checkr Customer Support Manager to troubleshoot the issue.

Uses and limitations of the staging account

The staging account is built to mimic the production environment and allow developers to build without running production background screenings and incurring a charge. Staging account uses mocked candidate data, and does not support the following functionality available in the production environment:

• Post adverse action is not supported
• Invitations do not expire
• Invoices are not created
• Analytics are not available

Please reach out to your Checkr Account Executive or Customer Success Manager if you require additional status, report, or state test cases.

Once you have access set up to log into Checkr, go to Developer Settings in the Checkr Dashboard. Click Create Key > Secret to generate a new Secret Key for your staging environment.

Your production API key is also available from this Developer Settings page. Note that your production key will not be enabled for Reports until you contact clients@checkr.com and request that your account be enabled for live requests.

For more information on using Checkr's Staging environment, see the Requesting a Staging Account section below.

Checkr provides support for several API clients, allowing you to explore the Checkr APIs. Download and install Postman or Insomnia, then click the buttons below to install the Checkr APIs. Or use our OAS3 API spec to work with the tooling of your choice.

Configure your API client

Configure your API client using the API key from the Developer Settings page in your Checkr Dashboard. Then use your local client to execute any Checkr API requests. We provide sample parameters and payloads throughout these developer guides to help you in your journey.

Note: Checkr APIs are updated frequently. Use your selected method to reimport our APIs to evaluate our most recent versions.

Checkr API host URLs:

• Production: https://api.checkr.com/v1
• Staging (if you have been given access): https://api.checkr-staging.com/v1

Use HTTP Basic authentication to authenticate with Checkr, with your API key as the username and an empty password. When using curl, use the -u option to specify your API key. (Note the colon following the API key in the examples. It tells cURL to send an empty password.)

Note that staging environment requests are free and return fake data. Once you are production-ready, please email clients@checkr.com and we will enable live requests.

Create a Candidate by passing the required PII to Checkr.

Remember to replace "YOUR_SECRET_API_KEY" with your Secret API key in the cURL example on the right. See Candidates for more details on creating Candidates.

Notes:

• The Candidate object represents the candidate to be screened.
• The copy_requested boolean captures whether or not the candidate has requested a copy of their background check upon completion. If true, Checkr will automatically send a copy of the background check to the passed email address on your behalf.
• If using a Checkr-hosted candidate experience, the only strictly required parameter for creating a Candidate in Checkr is email. We recommend that the candidate's phone number also be provided when creating the Candidate object, as it will be required to authenticate the candidate when they log into the Candidate Portal.
• If using a custom self-hosted flow, the required attributes include first_name, middle_name or no_middle_name, last_name, and dob.
• If the Report's package includes any criminal check, ssn and zipcode are required attributes.
• If requesting a Motor Vehicle Report, Checkr requires driver_license_number and driver_license_state.
• Other Candidate-specific parameters are defined in the Candidate resource below.

Candidate creation response

Checkr responds immediately with the resulting Candidate object, which includes the ID of the Candidate and a URI that points to the new Candidate object. Store the ID for this new Candidate object, which you'll need when creating a Report in the next step.

Use the Invitations resource to order a background check using the Checkr-Hosted Apply Flow. Checkr will send an email to the candidate, inviting them to provide their information and consent. Once the invitation is completed a Report is automatically created. The invitation is valid for 7 days, during which Checkr will send a follow-up notice every 24 hours, reminding the candidate to complete their invitation. 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 Package to use for the background check.
• work_locations: the candidate's work location, described using country, state, and city. (ISO-3166 alpha-2 format country code, two letter state code, and the name of the city)
• node (optional): the custom_id of the node associated with the background check. Required if any nodes exist on the account.

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.

Invitation creation response

Use the Checkr Candidate ID you have retrieved from Create a Candidate, 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).

Store the resulting Report ID and any of the requested Screening IDs. The ID for this new Report object is required to retrieve the Report. (Checkr will return IDs for all Screenings included in the requested Package. All other Screening IDs will be returned null.)

If webhooks are enabled, Checkr pushes a status change webhook event to the customer account's webhook URL with the structure shown in the Test Webhook Response to the right.

Use the resulting Report status (or other data elements) to execute subsequent workflows in your application or program.

Subscribing to webhooks is the recommended approach for accessing the report information and status, since it provides near real-time updates and frees the customer from having to poll our API for this information.

While Checkr recommends listening to the report.completed webhook to retrieve the results of a report, you can also retrieve the same information by performing a GET request to the specific URL of the report.

Retrieve the Report created in the previous step by using your Secret API key and Report ID into the cURL command shown to the right.

Retrieve Report response

Note that the Report is now a full Report with a status of clear, indicating that no violations or criminal background have come up for this Report.

See Embedding Resources if you wish to embed the full contents of individual screenings (SSN Trace, Sex Offender Registry Search, Global Watchlist Search) in the server response. You can also retrieve those resources using the IDs provided in the server response.

Webhook responses and completed Reports both contain the same information about the results of a criminal screening: the status of the report which can be complete, the result of the report which can be null, clear, or consider, and the assessment of the report, which can be null, eligible, review, or escalated.

A completed report with result of clear can be interpreted as that report having no items listed on the candidate's record that must be reviewed. A result of consider indicates that there are items on the candidate's record that may require consideration.

A report contains an assessment if the account has Assess enabled. The assessment is returned as eligible, review, or escalated, according to the customer rules defined in Assess. For more information, see Assess in the Checkr User Guides.

In maintaining a compliant process as per FCRA legislation and EEOC guidelines, Checkr does not make any eligibility or hiring decisions (adjudicate) on our customers' behalf.

Use webhooks to receive updates on objects created with the API and to kick off additional workflows based on these events. Each time an event that you subscribed to occurs, Checkr submits a POST request to the designated webhook URL with information about the event. When the include_object option is ON, it also includes the related object.

The User-Agent for the requests will have the prefix Checkr-Webhook/.

To receive webhooks, use the Checkr Dashboard to configure a Webhook URL in the Developer Settings. A maximum of two webhook URLs may be configured. For more information about setting up webhooks, see the Account Settings article in the Checkr Help Center.

Your endpoint should respond to 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.

Webhook logs can be found on the dashboard: https://dashboard.checkr.com/webhook_logs

Checkr does not guarantee the delivery of events in the order in which they are generated. For example, a report with a result of consider might generate the follow events:

report.completed
report.engaged

Your integration should not expect the delivery of these events to be in this order and should handle this accordingly. For example, you can fetch the report object, and look at report.assessment if you happen to receive the report.completed event later.

For greater security, verify that the requests you receive come from Checkr.

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

Note: Accounts without an API key will have X-Checkr-Signature set to "Please create an API key to check the authenticity of our webhooks."

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.

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". For robust webhook handling, we recommend that you account for the following:

• Duplicate reports (idempotency)
• Webhook misses

As a best practice, Checkr recommends that you build a safety net to account for duplicate reports. One option might be to build in a function ahead of the status tracker, which copies only one report.completed update per Candidate or Report. This works well with an additional time threshold assigned. (For example, a report is only considered a duplicate if it's within 60 minutes of a previous iteration of that report.)

To address missed webhook updates, you may also consider adding a function to send an alert if no report.completed update is sent within a certain number of days.

Verification events are issued during the Exception process when a candidate is issued or has responded to a request to verify submitted PII.

Verification events are issued for exceptions which occur to ask candidates to confirm their Social Security Number, Driver License information, or Education and Employment Verification information.

The list of possible verification types that are in the webhook payload (verification_type inside the data object) can be found here.

Note: When verifications are automatically processed, and do not require manual input, the verification.processed webhook is sent immediately after the verification.completed webhook. These two webhooks may not arrive “in order”.

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 our Checkr Partner Application form to connect with our Business Development team.

Please see our Checkr Partner Developer Guides for more complete information on building your partner integration with Checkr, and allowing your customers to use Checkr functionality from within your app.

The Checkr API offers significant flexibility and opportunity for developers to build a unique background screening program tailored to their product or business needs. This section describes additional features and capabilities that our customers find valuable.

Checkr allows customers to create fully custom application flows for their candidates, using the Reports resource to build a self-hosted flow.

In this flow, you must collect and store both the candidate’s information and their consent within your application. You must also provide candidates the appropriate state- and city-specific disclosures for each screening type. Once obtained, you must 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 customer compliance (annual compliance audits).

Once all required information is present on the Candidate resource, creating a Report will initiate the background check.

For more information on your obligations under FCRA, and Checkr’s responsibilities as a Consumer Reporting Agency (CRA), check out our Compliance resources in the Help Center, particularly our articles about obligations under FCRA and disclosures and authorizations.

Note: Some screening types are not supported with the Reports flow, such as credit checks and complex occupational health screenings. Other screening types, like employment and education verifications, are supported but not recommended with this flow, as they require significant data entry. For more information, see Reports below.

Create a Report for an existing Candidate object. Use your API key and Candidate ID in the cURL command shown to the right.

Notes:

• The Report object represents a background check report.
• Depending on the selected Package, a Report may include any number of requested Screenings.
• Validation for inclusion of Candidate attributes (such as driver license number or SSN) is performed when you request a Report.
• Information requirements depend strictly on the Package requested. (For more information, see Packages, below.)
• This object includes your certification to Checkr that appropriate disclosures and authorization (such as consent) have been obtained from your candidate.

Report Creation response

Checkr responds immediately with the full Report object, which includes the ID of the Report and a URI that points to the new Report object.

Store the resulting Report ID and any of the requested Screening IDs. The ID for this new Report object is required to retrieve the Report. (Checkr will return IDs for all Screenings included in the requested Package. All other Screening IDs will be returned null.)

In addition to offering "point-in-time" background checks, Checkr offers ongoing check services through our Subscription and Continuous Check products.

A Subscription enables customers to order a repeating background check on a candidate on a user-defined time interval. Candidates must first complete an initial background check, after which customers may create a Subscription to repeat that background check on a user-defined interval. Subscriptions can be created, modified, or deleted both through the Checkr Dashboard and the Checkr API.

For more information, see Subscriptions: Run recurring background checks in the Checkr Help Center, or the Subscription resource below.

Continuous Checks allow customers to monitor their candidates' records. Continuous Check monitors real-time data sources, and looks for changes in a candidate's record. If Checkr identifies a change in the candidate's history, Continuous Check will automatically kick off follow-up searches in the appropriate jurisdictions and generate a new background check report.

For more information, see Continuous Check: The new standard of safety in the Checkr Help Center, or the Continuous Checks resource below. For information on using the Checkr Dashboard to order a Continuous Check package on a candidate, see Continuous checks in the Checkr Help Center.

While both Continuous Check and Subscriptions allow you to monitor your candidates' record, they should not be understood as equivalent to one another. Subscriptions generate a new report according to your defined cadence. Continuous Check continuously monitors multiple data sources, and generates a new report only if a change in your candidate's record is found. If you have additional questions about what makes the most sense for your business, please reach out to your Checkr Account Executive or Customer Success Manager.

Checkr also offers the ability to "upgrade" a report based on a prior set of screening results. The most common use case for this feature is to order a Package that includes both a Motor Vehicle Record (MVR) and a County Criminal Search. The report can be "upgraded" to run the County Criminal Search only after the MVR returns with a result. Checkr facilitates the following workflow:

1. Customer submits API request to Checkr for a candidate MVR
2. Checkr fulfills MVR, submits webhook response to customer with screening results
3. Customer determines if candidate passes or does not pass MVR requirements
4. If candidate passes MVR requirements:
   • Customer submits second API request for Checkr to "upgrade" the MVR report to a full criminal screening report, submitting a POST request to Checkr's /reports/{id} endpoint with the same Report ID and the new Package to request
   • Checkr conducts the criminal screening as described in Overview of API calls and callbacks
5. If the candidate does not pass MVR requirements:
   • Customer does not submit second API request to Checkr

For more information on upgrading a Report, please see Update an existing Report below.

Please note: Only reports which include a Candidate SSN may be upgraded, and only within 30 days of Report creation. Attempts to upgrade a report which does not include an SSN will return a 400 error: "Candidate must have SSN to upgrade report." Requests to upgrade an older report will result in a 400 error, "Report too old to upgrade."

To use the Candidate SSN endpoint, you must generate an RSA key-pair for your account, and share the public key with Checkr. Checkr will use this public key to encrypt the SSN and securely share it with your integration.

Generating a Key Pair

Run the following command in a bash session to generate a private key. This will generate a file named private.pem containing your private key.

openssl genrsa -out private.pem -aes256 4096

Once your private key is generated, run the following command. This will generate a file named public.pem containing your public key.

openssl rsa -in private.pem -out public.pem -outform PEM -pubout

With both keys generated, send your public key to your Customer Success Manager. Do not share your private key. If your private key is exposed let us know as soon as possible so that we can secure your candidates' information.

The Content-Type entity header is used to describe the media type of a resource. In requests, a Content-Type header tells the server what type of data is being sent. In responses, it tells the client what type of data the returned content actually is.

Our default is to accept data as application/x-www-form-urlencoded (which is typical for most websites you interact with), but you are free to send other data types, like application/json, as it suits you. Simply specify the Content-Type in the header of the request.

By default, an API response contains the requested resource, and provides the IDs of related resources. You can also request related resources to be embedded in the initial response.

The include parameter specifies the names of resources that should be embedded in the response. Resources to embed must be comma-separated.

Pagination is enabled for endpoints that return a list of records.

There are two parameters that control pagination: page, which specifies the page number to retrieve, and per_page, which indicates how many records each page should contain. The default value of per_page is 25 records.

Paginated responses include the following attributes:

In order to provide a high-quality of service for all customers, our API is rate limited. The current limit is 1200 requests per minute across all endpoints. We reserve the right to adjust the rate limit for given endpoints.

If the rate limit is exceeded, the API responds with a HTTP 429 "Too Many Requests" status code. The response has a X-Ratelimit-Reset header that tells you when the rate limit count will reset.

Here are the headers related to rate limiting that our API returns for any requests:

Staying under the limit

Here are some recommendations to stay under the limit:

• Subscribe to Checkr webhooks to get updates about a report's activity instead of polling.
• If you do anticipate situations where you could exceed the limit, we recommend using an exponential backoff (wait 2 seconds, then 5, then 10, then 30, etc.) and retrying the API call.

The Checkr API supports idempotency in POST requests. Use this feature to safely repeat POST requests without accidentally creating the same reports or candidates multiple times.

First, provide an Idempotency-Key: <key> header to the POST request. This header value will be used server side to recognize retries of the same request.

The client side must then generate a unique value for every POST request, and re-use the same header value in any subsequent retry attempts. We recommend the use of V4 UUIDs to avoid collisions.

When serving the request with a new idempotency key, Checkr service will save the response (including status code, headers, body) for the first request if it is successful (2xx status), and return the saved response for later requests with the same idempotency key.

Note: The idempotency key expires after 24 hours. Retries with an expired idempotency key will be handled as new requests.

The Checkr API supports alphanumeric character input, as well as accented characters and some punctuation marks.

Corresponding regex character ranges: [a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]

Supported accented characters

Checkr has compiled the following table of valid driver license number input per state. To avoid errors, we suggest that you implement driver license number validation for both the Candidates and Driver Licenses endpoints.

The Checkr API validates submitted email addresses using the industry standard RFC 5322. The string length must be <=255, and the domain must be valid and configured to accept email. (For example: gmail.com is a valid domain, while gmeil.con is not.)

To avoid errors, we suggest that you validate emails used in your candidate creation requests.

Workflow types

Workflow types are high-level flows the employee can select at the moment of creating an I9 form, it affects what will be the filling experience is from a candidate’s perspective.

Form I9 Order Progress

Represents the current status of the I-9/e-Verify process.

Form I9 Open Tasks

Represents tasks that must be completed by the employer/customer.

Checkr's product incorporates SSN field controls designed to not accept SSNs with the following characteristics:

• SSNs without exactly 9 numeric characters
• SSNs that start with 666 (666-34-3768)
• SSNs that start with 9 (967-65-4325)
• SSNs that are a single digit (111-11-1111)
• SSNs that are sequential digits (123-45-6789)

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

Screenings can be canceled due to various scenarios. Here is a list of the current cancellation reasons and their descriptions.

Verification type values that indicate additional information or actions requested from a candidate. These types are shown inside of webhooks and from the API for verifications. For more information about verifications please visit the links for the webhook events or the api.

The Account resource includes account information and settings. Account information can be updated from the Dashboard. Some Account settings, like available_screenings, can be updated only by Checkr. Contact our Customer Success team for more information.

The User resource includes user information and role assignments. Users can be invited and assigned roles from the Dashboard.

Use the Hierarchy endpoint to structure your Account as a grouping of individual entities (Nodes) that represent your business with respect to your hiring and background check needs.

The parent-child relationship of Nodes may then be used to manage the relationship of your Packages and other account settings to Users and Candidates within your Account. Once defined, use the Checkr Dashboard to assign Nodes to Users, Packages, your Positive Adjudication Matrix, and other aspects of your Checkr Account.

Specifying a unique ID (custom_id) for each Node in the hierarchy allows you to edit the structure of your hierarchy without dissociating any Packages, PAMs, or Users assigned directly to the individual nodes. As nodes are moved to different locations within the hierarchy they will inherit Packages or PAMs from their new parent that may differ from the last, but Packages assigned directly to the node will not change.

Nodes are the individual entities that comprise an Account Hierarchy. If hierarchy is enabled for your Checkr Account, this endpoint may be used to retrieve a list of all Account Nodes. To create Nodes, use the Create Hierarchy endpoint.

Candidates represent people who have applied for positions within your company, and have agreed to a background check. Use the Candidate object to collect all Personally Identifiable Information (PII) for a candidate, and all relevant Checkr information, including any generated Reports, or attached Geos.