# Introduction Checkr is a modern, [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API-driven background screening service. The Checkr API uses resource-oriented URLs, supports HTTPS authentication and HTTPS verbs, and leverages [JSON](http://www.json.org/) 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](/apis/openapi/ssn-trace) below or read the Checkr Help Center articles on [Screening Types](https://help.checkr.com/hc/en-us/sections/203637147-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. The cURL command is used for all examples in the Checkr API documentation. ## Other resources For information about using the Checkr Dashboard, and [compliance](https://help.checkr.com/hc/en-us/sections/203637107-Compliance) and regulatory aspects of background checks, visit the [Checkr Help Center](https://help.checkr.com). 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](https://learn.checkr.com). Help Center Compliance, regulatory guidance, and Dashboard documentation. Learning Center Targeted learning paths for Recruiters, Adjudicators, and Program Administrators. Screenings Full list of available screening types. ## Understand the screening process 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. ### 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](#designing-your-workflow). ### 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. ### 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. ### 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. ### 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. ### 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. ## Get credentialed 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)](https://www.ftc.gov/enforcement/rules/rulemaking-regulatory-reform-proceedings/fair-credit-reporting-act). 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](https://www.transunion.com/data-reporting/getting-started). ### 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](#self-hosted-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. ## API keys 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](/apis/getting-started#request-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](https://github.com/checkr/checkr-js), 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](https://help.checkr.com/hc/en-us/articles/360010450474-Account-Settings#developer) page. 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](https://help.checkr.com/hc/en-us/articles/360010450474-Account-Settings#developer) 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. API Keys in Developer Settings ## Designing your workflow 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. | Option | Benefits | Disadvantages | | --- | --- | --- | | Checkr Dashboard experience | No developer investment needed to get up-and-running | Least control over user experienceLeast amount of flexibility around automated workflows | | Checkr-hosted candidate experience | Easy to implement and get up-and-runningCheckr hosts and maintains compliance language | Less control over user experienceLess flexibility around API-specific automated workflows | | Self-hosted candidate experience | Seamless, customizable user experiencePotential for higher candidate conversion ratesAbility to measure conversion at each stage | Requires greater engineering resourcesCustomer is responsible for presenting and capturing all legal disclosure and consent forms and maintaining ongoing compliance with FCRA and state/locality regulationsCustomer must have adequate legal resources to provide ongoing review of compliance | ### 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](https://help.checkr.com/hc/en-us/articles/217084017-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](/apis/openapi/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. 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](/apis/advanced-features#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](https://en.wikipedia.org/wiki/Electronic_Signatures_in_Global_and_National_Commerce_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. 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 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](https://help.checkr.com/hc/en-us/sections/360002119753-Checkr-Dashboard-User-Guide) in the Checkr Help Center.