Checkr.com API Docs (v1)

Introduction

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.

Introduction

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.

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.

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 assessment update of Clear or Consider through their selected method of API webhooks, email, or Checkr Dashboard notifications.

Clear and Consider are the default assessments. A Clear assessment can be interpreted as that report having no items listed on the candidate’s record that require consideration. A report with an assessment 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.

Get credentialed

Before gaining a Checkr test 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.

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 Staging Account below.

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.

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 experience
  • Least amount of flexibility around automated workflows
Checkr-hosted candidate experience
  • Easy to implement and get up-and-running
  • Checkr hosts and maintains compliance language
  • Less control over user experience
  • Less flexibility around API-specific automated workflows
Self-hosted candidate experience
  • Seamless, customizable user experience
  • Potential for higher candidate conversion rates
  • Ability to measure conversion at each stage
  • Requires greater engineering resources
  • Customer must host and maintain compliance language in their product

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 hosting your own candidate onboarding experience takes more developer time, it might not be as much time as you think. We've seen teams successfully deploy a new background check and onboarding flow in a single 2-week development sprint.

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.

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

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.

Getting Started

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

Note: Please reach out to clients@checkr.com before you start integrating with our API to learn about our approval process for production.

Get credentialed

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.

Get your API key

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.

Note: The Checkr Dashboard also lists access to our legacy Test Secret and Test Publishable Keys. Be certain to use the (live) Secret key, and not the Test Secret key in your staging enviroment.

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 Staging Account below.

Set up a local API client

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.

Run in Postman      Run in Insomnia}

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:

Authenticate with Checkr

Example authentication
$ curl https://api.checkr.com \
    -u YOUR_SECRET_API_KEY:

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

Create a Test Candidate
$ curl -X POST https://api.checkr.com/v1/candidates \
    -u [YOUR_API_KEY]: \
    -d first_name=Michael \
    -d middle_name=Gary \
    -d last_name=Scott \
    -d email=michael.scott@dundermifflin.com \
    -d phone=2035408926 \
    -d zipcode=06831 \
    -d dob=1964-03-15 \
    -d ssn=111-11-2001 \
    -d driver_license_number=981736076 \
    -d driver_license_state=CT \
    -d copy_requested=true \
    -d 'work_locations[][country]=US'

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

Test Candidate creation response
{
  "id":"551564b7865af96a28b13f36",
  "object":"candidate",
  "uri":"/v1/candidates/551564b7865af96a28b13f36",
  "created_at":"2018-08-17T01:08:18Z",
  "first_name":"Michael",
  "last_name":"Scott",
  "middle_name":"Gary",
  "mother_maiden_name":null,
  "dob":"1964-03-15",
  "ssn":"XXX-XX-2001",
  "email":"michael.scott@dundermifflin.com",
  "zipcode":"06831",
  "phone":"2035408926",
  "driver_license_state":"CT",
  "driver_license_number":"981736076",
  "copy_requested":true,
  "previous_driver_license_state":null,
  "previous_driver_license_number":null,
  "adjudication":null,
  "custom_id":null,
  "no_middle_name":false,
  "report_ids":[],
  "geo_ids":[]
}

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.

Create an Invitation

Create a Test Invitation
$ curl -X POST https://api.checkr.com/v1/invitations \
      -u [YOUR_API_KEY]: \
      -d candidate_id=551564b7865af96a28b13f36 \
      -d package=dunder_mifflin_executive \
      -d node=CHLD_e7c3ab7bf4ad \   // only if nodes exist on the account
      -d work_locations[][state]=CA \   // state required, city optional
      -d work_locations[][city]=San+Francisco

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

Test Invitation creation response
{
    "id": "551564b7865af96a28b13f36",
    "object": "invitation",
    "uri": "/v1/invitations/551564b7865af96a28b13f36",
    "invitation_url":
"https://apply.checkr.com/invite/try-checkr/290f9d6d6e46/test",
    "status": "pending",
    "created_at": "2015-05-14T17:45:34Z",
    "expires_at": "2015-05-21T17:45:34Z",
    "completed_at": null,
    "deleted_at": null,
    "package": "dunder_mifflin_executive",
    "candidate_id": "551564b7865af96a28b13f36",
    "report_id": null
    "tags": []
}

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

Listen for webhooks

Test webhook response
{
  "id": "507f1f77bcf86cd799439011",
  "object": "event",
  "type": "report.completed",
  "created_at": "2014-01-18T12:34:00Z",
  "data": {
    "object": {
      "id": "4722c07dd9a10c3985ae432a",
      "object": "report",
      "uri": "/v1/reports/532e71cfe88a1d4e8d00000d",
      "created_at": "2014-01-18T12:34:00Z",
      "received_at": "2014-01-18T12:34:00Z",
      "status": "clear",
      "result": "clear",
      "package": "driver_pro",
      "source": "api",
      "candidate_id": "e44aa283528e6fde7d542194",
      "ssn_trace_id": "539fd88c101897f7cd000001",
      "sex_offender_search_id": "539fd88c101897f7cd000008",
      "national_criminal_search_id": "539fd88c101897f7cd000006",
      "county_criminal_search_ids": [
        "539fdcf335644a0ef4000001",
        "532e71cfe88a1d4e8d00000c"
      ],
      "state_criminal_search_ids": [
        "539fdcf335644a0ef4000003",
        "532e71cfe88a1d4e8d000004"
      ],
      "motor_vehicle_report_id": "539fd88c101897f7cd000007"
    }
  },
  "account_id": "8e122cc56b8fa82d33c6118a"
}

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.

Retrieve a Report

Retrieve a Report
$ curl -X GET https://api.checkr.com/v1/reports/a13f4827d8711ddc75abc56ct

Retrieve the results of a report by performing a GET request to the specific URL of the report. For example, executing the command to the right retrieves the Report object below it.

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

Retrieve Report response
{
  "id": "a13f4827d8711ddc75abc56ct",
  "object": "report",
  "uri": "/v1/reports/a13f4827d8711ddc75abc56ct",
  "status": "clear",
  "result": "clear",
  "created_at": "2018-08-17T01:10:21Z",
  "completed_at": "2018-08-17T01:12:26Z",
  "revised_at": null,
  "upgraded_at": null,
  "turnaround_time": 52,
  "package": "dunder_mifflin_executive",
  "tags": [],
  "adjudication": null,
  "assessment": null,
  "source": "api",
  "candidate_id": "551564b7865af96a28b13f36",
  "county_criminal_search_ids": [],
  "municipal_criminal_search_ids": [],
  "document_ids": [],
  "federal_criminal_search_id": "5b64c62b67abb4002d3ec763",
  "global_watchlist_search_id": "5b64c5cf67abb400353ec6f7",
  "national_criminal_search_id": "5b64c5cf67abb400353ec6f5",
  "personal_reference_verification_ids": [],
  "professional_reference_verification_ids": [],
  "sex_offender_search_id": "5b64c5cf67abb400353ec6f6",
  "ssn_trace_id": "5b64c5cf67abb400353ec6f3",
  "state_criminal_search_ids": [],
  "terrorist_watchlist_search_id": "5b64c5cf67abb400353ec6f7",
  "facis_search_id": null,
  "arrest_search_id": null,
  "motor_vehicle_report_id": null,
  "self_disclosure_ids": []
}

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.

Parse the results

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 clear, consider, or 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.

Staging Accounts

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, confirm you are using the “Live” mode (do NOT use “Test” mode). Then 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, select Live, 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.

Webhooks

Generic webhook payload examples

include_object is ON

{
  "id": "1002d6bca6acdfcbb8442178",
  "object": "event",
  "type": "object.event",
  "created_at": "2018-08-17T01:12:43Z",
  "webhook_url": "https://notify.company.com/checkr",
  "data": {
    "object": {
      "id": "a13f4827d8711ddc75abc56ct",
      "object": "object",
      "uri": "/v1/objects/a13f4827d8711ddc75abc56ct",
      "created_at": "2018-08-17T01:10:21Z",
      "completed_at": "2018-08-17T01:12:26Z",
      // [...] full object included
    }
  }
}

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 per environment (test and live). For more information about setting up webhooks, see the Account Settings article in the Checkr Help Center.

Attributes

include_object is OFF

{
  "id": "1002d6bca6acdfcbb8442178",
  "object": "event",
  "type": "object.event",
  "created_at": "2018-08-17T01:12:43Z",
  "webhook_url": "https://notify.company.com/checkr",
  "data": {
    "object": {
      "id": "a13f4827d8711ddc75abc56ct",
      "object": "object",
      "uri": "/v1/objects/a13f4827d8711ddc75abc56ct"
    }
  }
}
Parameter Type Description
id string ID of the event.
object string Defines the object type: event.
type string The type of event. Values include: candidate.created, report.completed.
created_at timestamp iso 8601 format Timestamp for the event.
webhook_url string Webhook URL.
data hash Object associated with the event.
include_object boolean Should the related object be attached to webhook payload.

Supported webhook URLs

Type Format Description
HTTP / HTTPS http(s)://(<user>:<password>@)<hostname>/<path>
E.g.: https://notify.company.com/checkr
Notes: The endpoint to be reached must be public.
HTTP can be used only in a Test environment. Live environment webhooks must be HTTPS.
Basic Auth is supported by adding username:password@ in front of the hostname, credentials must be URL escaped.
SNS sns://<key_id>:<access_key>@<region>/<topic_owner>/<topic_name>
E.g.: sns://AKI95AMUAD5K:a2n66fVKX7%2BYJKid3@us-east-1/12048/checkr
AWS Simple Notification System (SNS)
Notes: Access Key must have only the Publish to SNS right in IAM.
Credentials must be URL escaped.

Responding to webhooks

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. Webhooks failing for more than 7 consecutive days are automatically deleted.

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

Order of events

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.

Securing webhooks

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:

echo -n "${request_body}" | openssl dgst -sha256 -hmac "${api_key}"

Code examples on how to do this can be found here.

Guarding against duplicate and missed report notifications

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.

Candidate events

Example Candidate event webhook payload
{
  "id": "58f8e550d991bb000db04005",
  "object": "event",
  "type": "candidate.created",
  "created_at": "2017-04-20T16:44:00Z",
  "webhook_url": "https://yourcompany.com/checkr/incoming",
  "data": {
    "object": {
      "id": "c373384e71a9a02098cb7421",
      "object": "candidate",
      "uri": "/v1/candidates/e44aa283528e6fde7d542194",
      "created_at": "2017-04-18T18:37:34Z",
      "first_name": "John",
      "last_name": "Smith",
      "middle_name": "Alfred",
      "mother_maiden_name": null,
      "dob": "1990-10-31",
      "ssn": "XXX-XX-1111",
      "email": "john.smith@example.org",
      "zipcode": "48071",
      "phone": "5555555555",
      "driver_license_state": "CA",
      "driver_license_number": "F111111",
      "copy_requested": true,
      "previous_driver_license_state": null,
      "previous_driver_license_number": null,
      "adjudication": "engaged",
      "custom_id": null,
      "no_middle_name": false,
      "report_ids": [
        "4722c07dd9a10c3985ae432a"
      ],
      "geo_ids": [],
      "metadata": {
        "custom_key": "custom_value"
      }
    }
  },
  "account_id": "e9b18321a51bdab376045be8"
}
Event Description
candidate.created A new Candidate has been created.
candidate.id_required An exception has been raised requiring a copy of the Candidate's identification.
candidate.driver_license_required An exception has been raised requiring a copy of the Candidate's driver license.
candidate.updated A Candidate has been updated.
candidate.pre_adverse_action An Adverse Action has been initiated on the Candidate.
candidate.post_adverse_action An Adverse Action has been completed on the Candidate.

Invitation events

Example Invitation event webhook payload
{
  "id": "1002d6bca6acdfcbb8442178",
  "object": "event",
  "type": "invitation.expired",
  "created_at": "2017-04-20T16:44:00Z",
  "webhook_url": "https://yourcompany.com/checkr/incoming",
  "data": {
    "object": {
      "id": "16241770f7f7be1c57c85176",
      "status": "expired",
      "uri": "/v1/invitations/16241770f7f7be1c57c85176",
      "invitation_url": "https://apply.checkr.com/invite/yourcompany/7499b8c558a6",
      "completed_at": null,
      "deleted_at": null,
      "expires_at": "2017-05-21T17:45:34Z",
      "package": "tasker_pro",
      "object": "invitation",
      "created_at": "2017-05-14T17:45:34Z",
      "candidate_id": "fcb0084f6cb2423c069a35b3",
      "report_id": null
    }
  },
  "account_id": "e9b18321a51bdab376045be8"
}
Event Description
invitation.created An Invitation has been created.
invitation.completed An Invitation has been completed.
invitation.expired An Invitation has expired.
invitation.deleted An Invitation has been canceled.

Verification events

Example Verification event webhook payload
{
  "id": "id",
  "object": "event",
  "type": "verification.processed",
  "created_at": "2018-07-12T00:06:40Z",
  "data": {
    "object": {
      "id": "verification_id",
      "object": "verification",
      "uri": "/v1/reports/report_id/verifications/verification_id",
      "created_at": "2018-07-12T00:06:39Z",
      "completed_at": "2018-07-12T00:17:02Z",
      "processed_at": "2018-07-12T00:17:04Z",
      "verification_type": "ssn_confirmation",
      "verification_url": "https://verifications.checkr.com/verifications/verification_id",
      "report_id": "report_id"
    }
  },
  "account_id": "account_id"
}

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.

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”.

Event Description
verification.created A verification is created and a request to upload a document or enter the data is forwarded to the candidate.
verification.completed A document is uploaded or data is entered by the candidate.
verification.processed The data gathered by the verification is processed manually or automatically and a decision is made for the continuation of the background check.

Report events

Example Report event webhook payload
{
  "id": "507f1f77bcf86cd799439011",
  "object": "event",
  "type": "report.completed",
  "created_at": "2014-01-18T12:34:00Z",
  "webhook_url": "https://yourcompany.com/checkr/incoming",
  "data": {
    "object": {
      "id": "4722c07dd9a10c3985ae432a",
      "object": "report",
      "uri": "/v1/reports/532e71cfe88a1d4e8d00000d",
      "created_at": "2014-01-18T12:34:00Z",
      "received_at": "2014-01-18T12:34:00Z",
      "status": "clear",
      "result": "clear",
      "package": "driver_pro",
      "candidate_id": "e44aa283528e6fde7d542194",
      "ssn_trace_id": "539fd88c101897f7cd000001",
      "sex_offender_search_id": "539fd88c101897f7cd000008",
      "national_criminal_search_id": "539fd88c101897f7cd000006",
      "county_criminal_search_ids": [
        "539fdcf335644a0ef4000001",
        "532e71cfe88a1d4e8d00000c"
      ],
      "state_criminal_search_ids": [
        "539fdcf335644a0ef4000003",
        "532e71cfe88a1d4e8d000004"
      ],
      "motor_vehicle_report_id": "539fd88c101897f7cd000007"
    }
  },
  "account_id": "e9b18321a51bdab376045be8"
}
Event Description
report.created A new Report has been created.
report.updated A Report has been updated while the background check is run. This event is triggered on select update events, which include:
  • Report Estimated Completion Time changed
  • Drug Screening update status event created
report.canceled A Report has been canceled.
report.upgraded A Report has been upgraded. Upgrades can be triggered either from an API call or from the Dashboard ("Upgrade" button). This is useful if you want to run a package (such as an MVR) and then upgrade it on completion (for example: add a County Criminal Search).
report.completed A Report has been completed.
report.suspended A Report has been suspended. Checkr is waiting for the candidate to provide additional documentation.
report.resumed A Report has resumed. (The candidate has provided documentation to a previously "suspended" Report.)
report.disputed A Report has been disputed by a candidate. Once a dispute has been completed, Checkr will trigger the report.completed webhook again with the appropriate Report status.
report.pre_adverse_action The Pre-Adverse Action notice has been sent to the candidate of that report.
report.post_adverse_action The Post-Adverse Action notice has been sent to the candidate of that report.
report.engaged A Report has been adjudicated as "engaged". Use this event to track either all candidates you have officially engaged, or simply those candidates with a "consider" background check report that you have engaged. This can be triggered either from an API call or from the dashboard ("Engage" button).

Adverse Action events

Example Adverse Action event webhook payload
{
  "id": "5c4fee84d5abd60049eaa4fe",
  "object": "event",
  "type": "adverse_action.notice_not_delivered",
  "created_at": "2019-01-29T06:11:16Z",
  "data": {
    "object": {
      "id": "5c4f46eb805e59e228baacdd",
      "object": "adverse_action",
      "uri": "/v1/adverse_actions/5c4f46eb805e59e228baacdd",
      "status": "pending",
      "created_at": "2019-01-28T18:16:11Z",
      "canceled_at": null,
      "post_notice_scheduled_at": null,
      "post_notice_ready_at": "2019-02-04T18:16:11Z",
      "delivery": {
        "state": "error",
        "updated_at": "2019-01-29T06:11:15Z",
        "reason": "No MX for bad-email-domain-client.com"
      },
      "individualized_assessment_engaged": false,
      "report_id": "report_id",
      "adverse_items": [
        {
          "id": "62532b9f6dd2279acc5eb3574bad5bc085892ecc",
          "object": "adverse_item",
          "text": "** ACCIDENT **"
        },
        {
          "id": "418759b62961971c0ce8d7a6858b6c6f457400d5",
          "object": "adverse_item",
          "text": "** ACCIDENT **"
        },
        {
          "id": "e911042a437d735bbcbb6a98ab500bc62fc2b88e",
          "object": "adverse_item",
          "text": "FAILURE TO WEAR SEAT BELT"
        },
        {
          "id": "09d83492f6a15b41e3e5c48a970df3a4f53e660c",
          "object": "adverse_item",
          "text": "OBSTRUCTING PASSAGE OF OTHER VEHIC"
        }
      ]
    }
  },
  "account_id": "account_id"
}
Event Description
adverse_action.notice_not_delivered The Adverse Action notice is confirmed to be undeliverable to the candidate of that report. User action is required.

Package events

Example Package event webhook payload
{
  "id": "1002d6bca6acdfcbb8442178",
  "object": "event",
  "type": "package.created",
  "created_at": "2017-04-20T16:44:00Z",
  "webhook_url": "https://yourcompany.com/checkr/incoming",
  "data": {
    "object": {
      "id": "e44aa283528e6fde7d542194",
      "object": "package",
      "uri": "/v1/packages/e44aa283528e6fde7d542194",
      "apply_url": "https://apply.checkr.com/apply/customer-services-inc/532c20ea819b",
      "created_at": "2014-01-18T12:34:00Z",
      "deleted_at": null,
      "name": "Driver Pro",
      "slug": "driver_pro",
      "price": 6500,
      "screenings": [
        {
          "type": "ssn_trace",
          "subtype": null
        },
        {
          "type": "county_criminal_search",
          "subtype": "7years"
        },
        {
          "type": "national_criminal_search",
          "subtype": "standard"
        },
        {
          "type": "sex_offender_search",
          "subtype": null
        },
        {
          "type": "global_watchlist_search",
          "subtype": null
        },
        {
          "type": "motor_vehicle_report",
          "subtype": null
        }
      ]
    }
  }
}
Event Description
package.created A Package has been created.
package.updated A Package has been updated.
package.deleted A Package has been deleted.

Continuous Check events

Example Continuous Check event webhook payload
{
  "id": "6164822db059440001101d93",
  "object": "event",
  "type": "continuous_check.confirmation_required",
  "created_at": "2021-10-11T18:27:57Z",
  "data": {
    "object": {
      "object": "continuous_check",
      "id": "d56cdf24dca36bd1cb65aebe",
      "candidate_id": "7c445ec8dd78d534436c6ead",
      "created_at": "2021-09-02T17:22:17Z",
      "node": "zpy8orej4r614ize",
      "type": "mvr",
      "work_locations": [
        {
          "country": "US",
          "state": "CA",
          "city": "San Francisco"
        }
      ]
    }
  },
  "account_id": "57f79ea983381984e6a6e61a"
}
Event Description
continuous_check.subscription_error An error occurred when attempting to enroll a Candidate in Continuous MVR.
continuous_check.confirmation_required A Candidate has been unenrolled from Continuous MVR due to stale or invalid PII. The Candidate sumbitted updated information through the Checkr exception process. Action is required to re-enroll the Candidate.

Checkr Partners

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.

Checkr Partner Developer Guides

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.

Advanced Features

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.

Creating a fully custom apply flow

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
$ curl -X POST https://api.checkr.com/v1/reports \
    -u [YOUR_API_KEY]: \
    -d package=dunder_mifflin_executive \
    -d candidate_id=551564b7865af96a28b13f36

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

Test Report creation response
{
  "id": "a13f4827d8711ddc75abc56ct",
  "object": "test_report",
  "uri": "/v1/reports/a13f4827d8711ddc75abc56ct",
  "status": "pending",
  "result": null,
  "created_at": "2018-08-17T01:10:21Z",
  "completed_at": null,
  "revised_at": null,
  "upgraded_at": null,
  "turnaround_time": null,
  "package": "dunder_mifflin_executive",
  "tags": [],
  "adjudication": null,
  "assessment": null,
  "candidate_id": "551564b7865af96a28b13f36",
  "county_criminal_search_ids": null,
  "document_ids": [
    "865de4344ac6d05209c83ef5"
  ],
  "federal_criminal_search_id": "5b64c62b67abb4002d3ec763",
  "global_watchlist_search_id": "5b64c5cf67abb400353ec6f7",
  "national_criminal_search_id": "5b64c5cf67abb400353ec6f5",
  "personal_reference_verification_ids": [],
  "professional_reference_verification_ids": [],
  "sex_offender_search_id": "5b64c5cf67abb400353ec6f6",
  "ssn_trace_id": "5b64c5cf67abb400353ec6f3",
  "state_criminal_search_ids": [],
  "terrorist_watchlist_search_id": "5b64c5cf67abb400353ec6f7",
  "facis_search_id": null,
  "arrest_search_id": null,
  "motor_vehicle_report_id": null
}

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

Ordering Subscriptions or Continuous Check services

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 Enroll a Candidate in Continuous Check 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.

Upgrading a report

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."

Configuring encryption for the SSN resource

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 using Sendr. 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.

Reference

Test Mode

Checkr’s Test Mode is a legacy testing environment that provides very limited testing scenarios and should be used only to test basic connectivity. Use the Staging Account described above for more in-depth testing.

Note: Test Mode does not support Account Hierarchy or Work Location. If your account has this functionality enabled (check if “Account Hierarchy” tab exists under “Account Settings”), you cannot use Test Mode.

The following test data is available for Test Mode:

Test SSNs

  • Test SSNs affect the SSN trace and all criminal screenings.
  • SSN 111-11-2001 returns a criminal screening with status clear.
  • SSN 111-11-2002 returns a criminal screening with status consider.
  • SSN 111-11-2010 returns a criminal screening with status pending.

Test driver licenses

  • Test driver licenses affect only the Motor Vehicle Report.
  • CA driver license with number F1112001 returns an MVR with status clear.
  • CA driver license with number F1112002 returns an MVR with status consider.

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

Content-Type

Example request
$ curl -X POST https://api.checkr.com/v1/candidates \
    -H "Content-Type: application/json" \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d '{"first_name": "John", "middle_name": "Alfred", "last_name": "Smith", "email": "john.smith@gmail.com"}'

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.

Embedding Resources

Example request
$ curl -X GET https://api.checkr.com/v1/reports/59b650f567e1dd0f01422b92\
    ?include=candidate,ssn_trace,county_criminal_searches \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

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

Example paginated request
$ curl -X GET https://api.checkr.com/v1/candidates?page=2&per_page=25 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
Example paginated payload
{
  "data": [
    {
      "id": "e44aa283528e6fde7d542194",
      "object": "candidate",
      "uri": "/v1/candidates/e44aa283528e6fde7d542194",
      "created_at": "2014-01-18T12:34:00Z",
      "first_name": "John",
      "middle_name": "Alfred",
      "no_middle_name": false,
      "last_name": "Smith",
      "mother_maiden_name": null,
      "email": "john.smith@gmail.com",
      "phone": "5555555555",
      "zipcode": "90401",
      "dob": "1970-01-22",
      "ssn": "XXX-XX-4645",
      "driver_license_number": null,
      "driver_license_state": null,
      "previous_driver_license_number": null,
      "previous_driver_license_state": null,
      "copy_requested": false,
      "custom_id": null,
      "report_ids": []
    },
    {
      "id": "8b6eb2bf554ebbef7b6f885a",
      "object": "candidate",
      "uri": "/v1/candidates/8b6eb2bf554ebbef7b6f885a",
      "created_at": "2014-01-18T12:34:00Z",
      "first_name": "Michael",
      "middle_name": null,
      "no_middle_name": true,
      "last_name": "Johnson",
      "mother_maiden_name": null,
      "email": "michael.johnson@gmail.com",
      "phone": "5555555555",
      "zipcode": "94407",
      "dob": "1970-01-22",
      "ssn": "XXX-XX-8605",
      "driver_license_number": null,
      "driver_license_state": null,
      "previous_driver_license_number": null,
      "previous_driver_license_state": null,
      "copy_requested": false,
      "custom_id": null,
      "report_ids": []
    }
  ],
  "object": "list",
  "next_href": null,
  "previous_href": "http://api.checkr.com/v1/candidates?page=1&per_page=25",
  "count": 27
}

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.

Parameters Description
page integer
greater than or equal to 1
per_page integer
between 0 and 100

Paginated responses include the following attributes:

Attributes Description
count integer
the total number of items
data array
list of objects
next_href string
URI to fetch the next page of results
object string
"list"
previous_href string
URI to fetch the previous page of results

Rate limiting

Example rate limiting request
$ curl -I -X GET https://api.checkr.com/v1/reports/59b650f567e1dd0f01422b92 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

< X-Ratelimit-Limit: 600
< X-Ratelimit-Remaining: 9
< X-Ratelimit-Reset: 2018-02-02T16:39:00Z

In order to provide a high-quality of service for all customers, our API is rate limited. The current limit is 600 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:

Header Description
X-Ratelimit-Limit Number of requests allowed per minute
X-Ratelimit-Remaining Remaining number of requests allowed for the current minute
X-Ratelimit-Reset Time at which the rate limit count resets

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 and retrying the API call.

Idempotency support

Example idempotent report creation request
$ curl -v -X POST https://api.checkr.com/v1/reports \
  -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
  -H 'Idempotency-Key: 40b23921-c005-4ec7-832a-3ae023dbbc11' \
  -d package=driver_pro \
  -d candidate_id=be529e5d8cc5ad26e655ce89

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.

Supported characters

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

ª µ º À Á Â Ã Ä Å Æ
Ç È É Ê Ë Ì Í Î Ï Ð
Ñ Ò Ó Ô { Ö Ø Ù Ú Û
Ü Ý Þ ß à á â ã ä å
æ ç è é ê ë ì í î ï
ð ñ ò ó ô õ ö ø ù ú
û ü ý þ ÿ ' . , -

Driver License validation

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.

State Validation Criteria Regex
AL 7-8 Numeric /\A\d{7,8}\z/
AK 7 Numeric /\A\d{7}\z/
AZ (1 Alpha + 8 Numeric) OR 9 Numeric /\A[A-Z]{1}\d{8}\z/ OR /\A\d{9}\z/
AR 9 Numeric /\A\d{9}\z/
CA 1 Alpha + 7 Numeric /\A[A-Z]{1}\d{7}\z/
CO 9 Numeric /\A\d{9}\z/
CT 9 Numeric /\A\d{9}\z/
DE 2-7 Numeric /\A\d{2,7}\z/
DC 7-9 Numeric /\A\d{7,9}\z/
FL 1 Alpha + 12 Numeric /\A[A-Z]{1}\d{12}\z/
GA 9 Numeric /\A\d{9}\z/
HI ("H" + 8 Numeric) or 9 Numeric /\AH\d{8}\z/ OR /\A\d{9}\z/
ID (2 Alpha + 6 Numeric + 1 Alpha) or 9 Numeric /\A[A-Z]{2}\d{6}[A-Z]{1}\z/ OR /\A\d{9}\z/
IL 1 Alpha + 11-12 Numeric /\A[A-Z]{1}\d{11,12}\z/
IN 10 Numeric /\A\d{10}\z/
IA 9 Numeric or (3 Numeric + 2 Alpha + 4 Numeric) /(\A\d{9}\z)/ OR /(\A\d{3}[A-Z]{2}\d{4}\z)/
KS "K" + 8 Numeric /\A[K]{1}\d{8}\z/
KY 1 Alpha + 8 Numeric /\A[A-Z]{1}\d{8}\z/
LA ("0" + 7 Numeric) OR ("0" + 8 Numeric) OR 7 Numeric or 8 Numeric /\A[0]{0,1}\d{7,8}\z/
ME 7 Numeric /\A\d{7}\z/
MD (1 Alpha + 12 Numeric) OR ("MD" + 11 Numeric) /\A[A-Z]{1}\d{12}\z/ OR /\AMD\d{11}\z/
MA ("SA" + 7 Numeric) OR ("S" + 8 Numeric) OR 9 Numeric \ASA\d{7}\z OR \AS\d{8}\z OR \A\d{9}\z
MI 1 Alpha + 12 Numeric /\A[A-Z]{1}\d{12}\z/
MN 1 Alpha + 12 Numeric /\A[A-Z]{1}\d{12}\z/
MS 9 Numeric /\A\d{9}\z/
MO 9 Numeric OR (1 Alpha + 5-9 Numeric) OR (3 Numeric + 1 Alpha + 6 Numeric) /(\A\d{9}\z)/ OR /(\A[A-Z]{1}\d{5,9}\z)/ OR /(\A\d{3}[A-Z]{1}\d{6}\z)/
MT 13 Numeric or 9 Alpha-Numeric or (3 Alpha + 10 Numeric) /(\A\d{13}\z)/ OR

/(\A(\d|[A-Z]){9}\z)/ OR \ /(\A[A-Z]{3}\d{10}\z)/

NE 1 Alpha + 3-8 Numeric /\A[A-Z]{1}\d{3,8}\z/
NV 10 Numeric /\A\d{10}\z/
NH (2 Numeric + 3 Alpha + 5 Numeric) OR ("NHL" + 8 Numeric) /(\A\d{2}[A-Z]{3}\d{5}\z)/ OR /(\ANHL\d{8}\z)/
NJ 1 Alpha + 14 Numeric /\A[A-Z]{1}\d{14}\z/
NM 9 Numeric /\A\d{9}\z/
NY 9 Numeric OR 1 Alpha + 18 Numeric /(\A\d{9}\z)/ OR /(\A[A-Z]{1}\d{18}\z)/
NC 1-12 Numeric /\A\d{1,12}\z/
ND 9 Alpha-Numeric /\A(\d|[A-Z]){9}\z/
OH 2 Alpha + 6 Numeric OR 8 Numeric /\A[A-Z]{2}\d{6}\z/ OR /(\A\d{8}\z)/
OK (1 Alpha + 9 Numeric) or 9 Numeric /(\A[A-Z]{1}\d{9}\z)/ OR /(\A\d{9}\z)/
OR 5-7 Numeric OR (1 Alpha + 6 Numeric) /(\A\d{5,7}\z)/ OR /(\A[A-Z]{1}\d{6}\z)/
PA 8 Numeric /\A\d{8}\z/
PR 5-7 Numeric OR 9 Numeric /\A\d{5,7}\z/ OR /\A\d{9}\z/
RI 7-8 Numeric OR ("V" + 6 Numeric) /(\A\d{7,8}\z)/ OR /(\AV\d{6}\z)/
SC 3-10 Numeric /\A\d{3,10}\z/
SD 6-9 Numeric /\A\d{6,9}\z/
TN 7-9 Numeric /\A\d{7,9}\z/
TX 7-8 Numeric /\A\d{7,8}\z/
UT 4-10 Numeric /\A\d{4,10}\z/
VT 8 Numeric or (7 Numeric + "A") /(\A\d{8}\z)/ OR /(\A\d{7}A\z)/
VA (1 Alpha + 8 Numeric) OR 9 Numeric /\A[A-Z]{1}\d{8}\z/ OR /\A\d{9}\z/
WA (4-8 Alpha + 2-3 Numeric + 2 Alpha-Numeric) OR ("WDL" + 9 Alpha-Numeric) /\A[A-Z*]{4,8}\d{2,3}(\d|[A-Z]){2}\z/ OR /\AWDL([A-Z]|\d){9}\z/
WV 7 Alpha-Numeric /\A([A-Z]|\d){7}\z/
WI 1 Alpha + 13 Numeric /\A[A-Z]{1}\d{13}\z/
WY 9 Numeric /\A\d{9}\z/

Email address validation

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.

SSN validation

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)

Error codes

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

Status Code Response
400 SSN is invalid
400 Zipcode is invalid
400 Email is not a valid email address
400 First name must only contain letters, numbers, spaces, hyphens, apostrophes, periods, and commas
400 Last name must only contain letters, numbers, spaces, hyphens, apostrophes, periods, and commas
400 Report is too old to upgrade
400 Candidate must have a driver license number and a driver license state for the package mvr
400 Report has a pre-existing adverse action. See https://docs.checkr.com/#operation/updateReport
400 SSN is invalid. TIN was provided.
400 SSN has already been taken
400 First name must only contain letters, numbers, spaces, hyphens, apostrophes, periods, and commas", "Last name must only contain letters, numbers, spaces, hyphens, apostrophes, periods, and commas
400 Candidate must_not have middle name when no_middle_name flag is set to true for the candidate report_id=
400 Report driver license state not supported or not enabled for account
400 Candidate must be at least 16 years old
400 Candidate must be at least 18 years old
400 Candidate must have SSN for the package driver_premium
400 Candidate has reached the limit of Reports allowed
400 Middle name must only contain letters, numbers, spaces, hyphens, apostrophes, periods, and commas.
400 Number Driver license number must only contain letters, numbers, spaces, hyphens, and asterisks
400 Candidate must have middle name when no_middle_name flag is set for the candidate report_id=
400 Number can't be blank, State can't be blank, State is not a valid US state
400 No middle name can not be updated, No middle name must have middle name when no_middle_name flag is set to false for the candidate candidate_id=
403 Forbidden
403 Sorry, your account is not approved for production
403 Candidate has requested that their PII be removed
409 Duplicate geo, name: peninsulasw_wa, state: WA already exists
409 Duplicate report detected. No more than 3 reports per candidate can be created within a 24 hour period
409 Duplicate candidate detected. No more than 2 duplicate candidates can be created within a 24 hour period

Account

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.

Retrieve authenticated account details

Returns Account details for the authenticated account.

Authorizations:

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/account \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "account",
  • "adverse_action_email": "john.doe@example.com",
  • "api_authorized": true,
  • "authorized": true,
  • "available_screenings": [
    ],
  • "billing_email": "john.doe@example.com",
  • "company": {
    },
  • "compliance_contact_email": "compliance.team@example.com",
  • "created_at": "2020-01-07T00:26:49Z",
  • "default_compliance_city": "San Francisco",
  • "default_compliance_state": "CA",
  • "geos_required": false,
  • "name": "Acme Corp",
  • "purpose": "employment",
  • "support_email": "support@example.com",
  • "support_phone": "206-555-0188",
  • "technical_contact_email": "jane.smith@example.com",
  • "uri": "/v1/accounts/e44aa283528e6fde7d542194",
  • "uri_name": "acme-corp"
}

Create a new Account

Creates a customer Account associated with your Partner Application. Only Checkr Partners are authorized to use this endpoint.

Authorizations:
Request Body schema: application/json
client_id
required
string

Client credentials provided as part of your Partner Application.

oauth_authorize
boolean
Default: false

Allows skipping of the /oauth/authorize call

name
required
string

Name of Account displayed in the Dashboard.

default_compliance_city
string Nullable

Fallback compliance city if candidate location is not provided.

default_compliance_state
string Nullable

Fallback compliance state if candidate location is not provided. Format: ISO 3166-2:US.

purpose
required
string

Permissible purpose to run background checks. Determines which background checks the Account is credentialed for.

Values include: "employment" "business" "insurance" "tenant"
required
object
required
object

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/accounts \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d client_id=56269e3411a549fd07ed8d92 \
    -d name=Acme+Corporation \
    -d default_compliance_state=CA \
    -d purpose=employment \
    -d user[full_name]=Jeanette+Hughes \
    -d user[email]=user@example.com \
    -d company[dba_name]=Acme \
    -d company[industry]=72 \
    -d company[street]=123+Main+Street \
    -d company[city]=San Francisco \
    -d company[state]=CA \
    -d company[zipcode]=94107 \
    -d company[tax_id]=123456789 \
    -d company[incorporation_state]=CA \
    -d company[incorporation_type]=association \
    -d company[phone]=206-555-0100 \
    -d company[website]=https%3A%2F%2Fwww.example.com

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "account",
  • "adverse_action_email": "john.doe@example.com",
  • "api_authorized": true,
  • "authorized": true,
  • "available_screenings": [
    ],
  • "billing_email": "john.doe@example.com",
  • "company": {
    },
  • "compliance_contact_email": "compliance.team@example.com",
  • "created_at": "2020-01-07T00:26:49Z",
  • "default_compliance_city": "San Francisco",
  • "default_compliance_state": "CA",
  • "geos_required": false,
  • "name": "Acme Corp",
  • "purpose": "employment",
  • "support_email": "support@example.com",
  • "support_phone": "206-555-0188",
  • "technical_contact_email": "jane.smith@example.com",
  • "uri": "/v1/accounts/e44aa283528e6fde7d542194",
  • "uri_name": "acme-corp"
}

Hierarchy (Enabled by request)

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.

For more information on Checkr's Account Hierarchy Management tools, please see the Account Hierarchy Mangement User Guides in the Help Center.

Create Hierarchy

Creates a new or replaces an existing Account Hierarchy.

The Hierarchy endpoint performs ingestion asynchronously. Check the status of the ingestion by calling GET /v1/hierarchy/status. Once ingested, use the Checkr Dashboard to assign your nodes to Packages, PAMs, and Users.

Authorizations:
Request Body schema: application/json
required
Array of objects (HierarchyNode)

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/hierarchy \
    -H 'Content-Type: application/json' \
    -u d3a265269d18997528b04cfa82bc6a108c1b8553: \
    -d '{ "nodes": [{"name":"Acme Staffing", "tier": "department", "custom_id": "zpy8orej4r614ize"}, {"name":"Drivers Staffing", "tier": "divison", "custom_id": "ocquzig4k3whppfx", "parent_custom_id": "zpy8orej4r614ize"}]}'

Response samples

Content type
application/json
{
  • "sync_id": "account-da78fa2cd1e6ebee4b5975aa",
  • "time": "2020-02-11T00:27:14Z"
}

Retrieve Hierarchy (Deprecated)

Note: This endpoint is deprecated and will no longer be supported. Please use the new List existing Nodes endpoint instead.

Retrieves the current Hierarchy for the Account.

Returns the account hierarchy in its entirety, or from a specific node to its children. The returned JSON object will include the Packages assigned to each node in the dashboard. This is useful for building UIs that truncate the list of Packages displayed to a requester, or display only the nodes that are relevant to the requester.

Output is arranged hierarchically, with child nodes accessible through the parent node. Customers without large hierarchy mode enabled who do not specify pagination parameters will be returned the entire hierarchy. Customers with large hierarchy mode enabled and pagination parameters specified in this request will be returned the given page and number of results per page. If pagination parameters are not included, only the first page of the hierarchy will be returned.

Note: Customers with large hierarchy mode enabled will see a different response. Please reach out to clients@checkr.com if you have any questions.

Authorizations:
query Parameters
node_custom_ids
Array of strings

An array of custom_ids for the nodes to return. Returns the portion(s) of the Account Hierarchy matching the input nodes and their descendants.

page
number Nullable

Specifies the page to retrieve. The default page is 1.

per_page
number Nullable

Indicates how many nodes each page should contain. The default per_page value is 20.

Responses

Request samples

$ curl https://api.checkr.com/v1/hierarchy \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "sync_id": "account-da78fa2cd1e6ebee4b5975aa",
  • "time": "2020-01-01T08:00:00Z",
  • "nodes": [
    ]
}

Retrieve Hierarchy update status

Returns the status of the latest Hierarchy ingestion request.

This call requires no input, and is provided as a means to determine the progress of an asynchronous POST /hierarchy request.

Authorizations:

Responses

Request samples

$ curl https://api.checkr.com/v1/hierarchy/status \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "hierarchy_present": true,
  • "hierarchy_pending": false,
  • "latest_ingestion": {
    }
}

Nodes

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.

For more information on Checkr's Account Hierarchy Management tools, please see the Account Hierarchy Mangement User Guides in the Help Center.

List existing Nodes

Returns a list of existing Nodes that make up the current Account Hierarchy.

  • If include=packages is passed, each Node object in the response will include a "packages" field. This will be an array of strings representing the slugs of the account Packages that are assigned (directly or indirectly) to the given Node. This field can be used to build UIs that truncate the list of Packages displayed to a requester, or to display only the nodes that are relevant to the requester.

  • If include=packages is not passed, no package information will be included in the response.

This endpoint uses pagination; please see the corresponding reference page for details.

Authorizations:
query Parameters
include
string

Includes a "packages" array with each Node object, containing a list of slugs for packages that are assigned to that node or its ancestors.

Value: "packages"
Example: include=packages
page
number Nullable

Specifies the page number to retrieve.

per_page
number Nullable

Indicates how many records each page should contain. The default value is 25 records.

order_by
string Nullable

Returns records sorted by custom_id or created_at. If neither is specified, records will be sorted by created_at.

Values include: "custom_id" "created_at"
Example: order_by=custom_id
order
string Nullable

Returns records listed in ascending or descending order of the order_by parameter. If neither is specified, records will be listed in ascending order.

Values include: "asc" "desc"
Example: order=desc

Responses

Request samples

$ curl https://api.checkr.com/v1/nodes?include=packages \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "object": "list",
  • "next_href": "http://example.com",
  • "previous_href": "http://example.com",
  • "count": 2,
  • "data": [
    ]
}

Candidates

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.

Create a new Candidate

Creates a new Candidate resource.

Required attributes

The Candidate resource’s required attributes vary depending on its intended use. If this resource is to be used in conjunction with the Invitations API (in which the invitation apply form collects the Candidate's personal information), the only strictly required Candidate attribute is email.

If this resource is to be used to generate any other report type, other personal information is also required.

Attributes required to generate a Report include:

  • first_name
  • middle_name or no_middle_name
  • last_name
  • dob

Attributes required to generate a Report with a criminal check screening:

  • ssn
  • zipcode

Attributes required to generate a report with a Motor Vehicle Record (MVR) screening:

  • driver_license_number
  • driver_license_state

See Driver License validation in the Reference section for a list of valid input by state.

Attributes recommended to generate a report with an Identity Document Verification screening:

  • phone (mobile phone number)

Validation for these attributes is performed when requesting a Report, as the requirements depend on the Package.

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)
Authorizations:
Request Body schema: application/json
first_name
required
string non-empty [a-zA-Z0-9 -'.,]*

Candidate’s first name.

middle_name
string[a-zA-Z0-9 -'.,]*

Candidate’s middle name. This field is required if no_middle_name is false.

no_middle_name
boolean
Default: false

Required if no middle_name is provided. true if the candidate has no middle name.

last_name
required
string non-empty [a-zA-Z0-9 -'.,]*

Candidate’s last name.

mother_maiden_name
string[a-zA-Z0-9 -'.,]*

Candidate’s mother’s maiden name.

email
required
string <email>

Candidate’s email address.

phone
string Nullable

Candidate’s phone number.

zipcode
string

Candidate’s 5-digit zip code.

dob
string <date>

Candidate’s date of birth.

ssn
string

Candidate’s Social Security Number. This value will be redacted in all return calls, except for the last four digits.

driver_license_number
string

Candidate’s driver license number.

driver_license_state
string

Candidate’s driver license state of issue. Format: ISO 3166-2:US.

previous_driver_license_number
string

Candidate’s previous driver license number.

previous_driver_license_state
string

State that issued the candidate’s previous driver license. Format: ISO 3166-2:US.

copy_requested
boolean
Default: false

If true, the candidate has asked to receive a copy of their report.

custom_id
string

Client-assigned unique ID for the Candidate. Can be used to map Checkr Candidate IDs to your internal tracking system, and to search for Candidates through both the Dashboard and the API.

geo_ids
Array of strings

Array of Geo IDs.

metadata
object (Metadata)

Up to 50 customer-defined key-value pairs. Use this parameter to store additional information on your candidate. For example: Use the key to map candidates to job_req_id, application_id, or branch_id. Keys must be 40 characters or less. Values must be 500 characters or less. For example: { "job_req_id": "12345" }

Array of objects (WorkLocation)

Required for non-US candidates.

Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/candidates \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d first_name=John \
    -d middle_name=Alfred \
    -d last_name=Smith \
    -d email=john.smith@gmail.com \
    -d phone=5555555555 \
    -d zipcode=90401 \
    -d dob=1970-01-22 \
    -d ssn=847-43-4645 \
    -d driver_license_number=F2111655 \
    -d driver_license_state=CA \
    -d 'work_locations[][country]=US'

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate",
  • "uri": "/v1/candidates/e44aa283528e6fde7d542194",
  • "first_name": "John",
  • "middle_name": "Alfred",
  • "no_middle_name": false,
  • "last_name": "Smith",
  • "mother_maiden_name": "Jones",
  • "email": "john.smith@gmail.com",
  • "phone": 5555555555,
  • "zipcode": 90401,
  • "dob": "1970-01-22",
  • "ssn": "XXX-XX-4645",
  • "driver_license_number": "F2111655",
  • "driver_license_state": "CA",
  • "previous_driver_license_number": "F1501739",
  • "previous_driver_license_state": "MD",
  • "copy_requested": false,
  • "custom_id": "string",
  • "report_ids": [
    ],
  • "geo_ids": [
    ],
  • "adjudication": "engaged",
  • "metadata": { }
}

List existing Candidates

Lists existing Candidates with the input parameters.

Note: This call will not return candidates with non-US work_locations. Use GET /candidates/{id} to retrieve candidates outside the US.

Authorizations:
query Parameters
email
string

Returns candidates with the input email address.

full_name
string

Returns candidates with the input full_name.

adjudication
string

Returns candidates with the input adjudication. Null if no adjudication has been made.

custom_id
string

Returns candidates with the input custom_id.

created_after
string <date-time>

Returns candidates created after the input date.

created_before
string <date-time>

Returns candidates created before the input date.

report_adjudicated_after
string <date-time>

Returns candidates adjudicated after the input date.

report_adjudicated_before
string <date-time>

Returns candidates adjudicated before the input date.

report_adjudicator_email
string

Returns candidates with a report adjudicated by someone with input adjudicator_email.

report_revised_after
string <date-time>

Returns candidates with a report revised after the input date.

report_revised_before
string <date-time>

Returns candidates with a report revised before the input date.

driver_license_number
string

Returns candidates with the input driver_license_number.

geo_id
string

Returns candidates with the input geo_id.

program_id
string

Returns candidates with the input program_id.

metadata
object

Returns candidates matching the input key-values. Input keys will be matched exactly. Input values will be pre- and post-pended with wildcards. (For example: A query for 1234 will return results for *1234*.)

page
number Nullable

Specifies the page number to retrieve.

per_page
number Nullable

Indicates how many records each page should contain. The default value is 25 records.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/candidates \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "object": "list",
  • "next_href": "http://example.com",
  • "previous_href": "http://example.com",
  • "count": 2,
  • "data": [
    ]
}

Update an existing Candidate

Updates an existing Candidate.

Attempts to update a field that cannot be updated will return a 400 error stating "... cannot be updated”. For example, attempting to update an SSN will return 400 stating "Candidate SSN can not be updated because it has reports”.

Updating geo_ids will replace all existing Geos. To keep existing geos, include their IDs in the update request. geo_ids cannot be updated if the candidate's work location is outside the US. Only fields with null values can be updated after a Report has been ordered for a Candidate with the exception of the following fields:

  • email
  • previous_driver_license_number
  • previous_driver_license_state
  • copy_requested
  • custom_id
  • geo_ids

Updating metadata with an empty value (null or empty object) will delete existing metadata. Individual keys may also be set and unset.

  • Adding a new key-value pair will maintain all existing key-value pairs.
  • Providing a new value for an existing key will update the old value to the new value.
  • Providing an empty value for an existing key will remove that key from the metadata object.
  • When all keys in the metadata object have empty values, the object will be deleted.
Authorizations:
path Parameters
id
required
string

The Candidate's ID.

Request Body schema: application/json
first_name
string non-empty [a-zA-Z0-9 -'.,]*

Candidate’s first name.

middle_name
string[a-zA-Z0-9 -'.,]*

Candidate’s middle name. This field is required if no_middle_name is false.

no_middle_name
boolean
Default: false

Required if no middle_name is provided. true if the candidate has no middle name.

last_name
string non-empty [a-zA-Z0-9 -'.,]*

Candidate’s last name.

mother_maiden_name
string[a-zA-Z0-9 -'.,]*

Candidate’s mother’s maiden name.

email
string <email>

Candidate’s email address.

phone
string Nullable

Candidate’s phone number.

zipcode
string

Candidate’s 5-digit zip code.

dob
string <date>

Candidate’s date of birth.

ssn
string

Candidate’s Social Security Number. This value will be redacted in all return calls, except for the last four digits.

driver_license_number
string

Candidate’s driver license number.

driver_license_state
string

Candidate’s driver license state of issue. Format: ISO 3166-2:US.

previous_driver_license_number
string

Candidate’s previous driver license number.

previous_driver_license_state
string

State that issued the candidate’s previous driver license. Format: ISO 3166-2:US.

copy_requested
boolean
Default: false

If true, the candidate has asked to receive a copy of their report.

custom_id
string

Client-assigned unique ID for the Candidate. Can be used to map Checkr Candidate IDs to your internal tracking system, and to search for Candidates through both the Dashboard and the API.

geo_ids
Array of strings

Array of Geo IDs.

adjudication
string

The adjudication for the Candidate’s most recently created Report.

Values include: "engaged" "pre_adverse_action" "post_adverse_action"
metadata
object (Metadata)

Up to 50 customer-defined key-value pairs. Use this parameter to store additional information on your candidate. For example: Use the key to map candidates to job_req_id, application_id, or branch_id. Keys must be 40 characters or less. Values must be 500 characters or less. For example: { "job_req_id": "12345" }

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d first_name=John \
    -d middle_name=Alfred \
    -d last_name=Smith \
    -d email=john.smith@gmail.com \
    -d phone=5555555555 \
    -d zipcode=90401 \
    -d dob=1970-01-22 \
    -d ssn=543-43-4645 \
    -d 'geo_ids[]=87f5bb4983eade22c55f4731&geo_ids[]=22b20140fc1adfae693ca35c'

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate",
  • "uri": "/v1/candidates/e44aa283528e6fde7d542194",
  • "first_name": "John",
  • "middle_name": "Alfred",
  • "no_middle_name": false,
  • "last_name": "Smith",
  • "mother_maiden_name": "Jones",
  • "email": "john.smith@gmail.com",
  • "phone": 5555555555,
  • "zipcode": 90401,
  • "dob": "1970-01-22",
  • "ssn": "XXX-XX-4645",
  • "driver_license_number": "F2111655",
  • "driver_license_state": "CA",
  • "previous_driver_license_number": "F1501739",
  • "previous_driver_license_state": "MD",
  • "copy_requested": false,
  • "custom_id": "string",
  • "report_ids": [
    ],
  • "geo_ids": [
    ],
  • "adjudication": "engaged",
  • "metadata": { }
}

Retrieve an existing Candidate

Retrieves an existing Candidate.

Authorizations:
path Parameters
id
required
string

The Candidate's ID.

query Parameters
include
string

Comma delimited string specifying the resources to be embedded in the returned Candidate object. See Embedding Resources.

Values include: "reports" "geos"
Example: include=reports,geos

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate",
  • "uri": "/v1/candidates/e44aa283528e6fde7d542194",
  • "first_name": "John",
  • "middle_name": "Alfred",
  • "no_middle_name": false,
  • "last_name": "Smith",
  • "mother_maiden_name": "Jones",
  • "email": "john.smith@gmail.com",
  • "phone": 5555555555,
  • "zipcode": 90401,
  • "dob": "1970-01-22",
  • "ssn": "XXX-XX-4645",
  • "driver_license_number": "F2111655",
  • "driver_license_state": "CA",
  • "previous_driver_license_number": "F1501739",
  • "previous_driver_license_state": "MD",
  • "copy_requested": false,
  • "custom_id": "string",
  • "report_ids": [
    ],
  • "geo_ids": [
    ],
  • "adjudication": "engaged",
  • "metadata": { }
}

Request PII removal for a Candidate

Requests the removal of PII from an existing Candidate

Requesting the removal of PII from a candidate who has already had PII removed will result in an error.

Authorizations:
path Parameters
id
required
string

The Candidate's ID.

Request Body schema: application/json
deletion_contact_email_address
required
string

Email address of person requesting candidate's PII removal.

deletion_contact_first_name
string

First name of person requesting candidate's PII removal.

deletion_contact_last_name
string

Last name of person requesting candidate's PII removal.

Responses

Request samples

Content type
application/json
{
  • "deletion_contact_email_address": "john.smith@gmail.com",
  • "deletion_contact_first_name": "John",
  • "deletion_contact_last_name": "Smith"
}

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate",
  • "uri": "/v1/candidates/e44aa283528e6fde7d542194",
  • "first_name": "John",
  • "middle_name": "Alfred",
  • "no_middle_name": false,
  • "last_name": "Smith",
  • "mother_maiden_name": "Jones",
  • "email": "john.smith@gmail.com",
  • "phone": 5555555555,
  • "zipcode": 90401,
  • "dob": "1970-01-22",
  • "ssn": "XXX-XX-4645",
  • "driver_license_number": "F2111655",
  • "driver_license_state": "CA",
  • "previous_driver_license_number": "F1501739",
  • "previous_driver_license_state": "MD",
  • "copy_requested": false,
  • "custom_id": "string",
  • "report_ids": [
    ],
  • "geo_ids": [
    ],
  • "adjudication": "engaged",
  • "metadata": { }
}

Reports

Reports provide all information relevant to a candidate’s requested background check. Reports include the status of the background check process, the list of searches included in the check, and the Package requested. Depending on the Package selected, a report may include any combination of Checkr Screenings listed below.

Reports are provided to candidates through the Candidate Portal, and as a PDF (if requested).

For more information on the searches listed, see Screenings (below), or Screening Types in the Checkr Help Center.

Create a new Report

Creates a new Report resource.

Notes:

  • This resource does not support the creation of reports which include international Packages. Use the /invitations API to order these reports.
  • Credit Checks require a complete Candidate address, and may not be initiated using the /reports API. Please use the /invitations API to initiate the Checkr-Hosted Apply Flow to order Credit Checks for your Candidates.
  • Creating a Report which includes an Occupational Health or Drug Check will automatically issue an email invitation to the candidate to schedule their appointment at a clinic of their choice.
Authorizations:
Request Body schema: application/json
candidate_id
required
string

ID of the Candidate screened.

package
required
string

Name of the Package. Example: driver_pro

node
string

Required for hierarchy-enabled accounts.

custom_id of the associated node.

Array of objects (SelfDisclosure)

Array of SelfDisclosures

Note: Self Disclosures may not be added, updated, or deleted after a Report has been created. The information provided in a Self Disclosure will not be included in the completed Report, and may be retrieved using GET /v1/reports/{id}?include=documents. See the Documents resource for more information.

Removing the requirement for the description, date, and location parameters greatly reduces the value of Self Disclosures. If your system mandates that these parameters be optional, work with your Checkr Customer Success Manager to disable the requirement.

Array of objects (WorkLocation)

Required for hierarchy-enabled accounts.

Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates.

tags
Array of strings

Array of tags for the Report.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/reports \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d package=driver_pro \
    -d candidate_id=e44aa283528e6fde7d542194

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "report",
  • "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
  • "status": "complete",
  • "result": "clear",
  • "includes_canceled": false,
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "revised_at": null,
  • "upgraded_at": null,
  • "turnaround_time": 90,
  • "package": "driver_pro",
  • "adjudication": "engaged",
  • "assessment": "eligible",
  • "source": "api",
  • "segment_stamps": [
    ],
  • "work_locations": [
    ],
  • "estimated_completion_time": "2019-07-31T00:00:00Z",
  • "candidate_story_ids": [
    ],
  • "candidate_id": "e44aa283528e6fde7d542194",
  • "drug_screening": {
    },
  • "ssn_trace_id": "539fd88c101897f7cd000001",
  • "arrest_search_id": "539fd88c101897f7cd000001",
  • "drug_screening_id": "539fd88c101897f7cd000001",
  • "facis_search_id": "539fd88c101897f7cd000001",
  • "federal_criminal_search_id": "539fd88c101897f7cd000001",
  • "federal_district_criminal_search_id": "539fd88c101897f7cd000001",
  • "federal_civil_search_id": "539fd88c101897f7cd000001",
  • "federal_district_civil_search_id": "539fd88c101897f7cd000001",
  • "global_watchlist_search_id": "539fd88c101897f7cd000001",
  • "sex_offender_search_id": "539fd88c101897f7cd000008",
  • "national_criminal_search_id": "539fd88c101897f7cd000006",
  • "county_criminal_search_ids": [
    ],
  • "personal_reference_verification_ids": [
    ],
  • "professional_reference_verification_ids": [
    ],
  • "motor_vehicle_report_id": "539fd88c101897f7cd000007",
  • "professional_license_verification_ids": [
    ],
  • "state_criminal_searches": [
    ],
  • "international_criminal_searches_v2_ids": [
    ],
  • "international_adverse_media_search_ids": [
    ],
  • "international_global_watchlist_search_id": "41007c751c9a15c892c0981a0400f3",
  • "international_education_verification_id": "41007c751c9a15c892c0981a040004",
  • "international_employment_verification_id": "41007c751c9a15c892c0981a040015",
  • "international_identity_document_validation_id": "41007c751c9a15c892c0981a040026",
  • "document_ids": [
    ],
  • "geo_ids": [
    ],
  • "program_id": "00166f9ff39ec7b453adfaec"
}

Update an existing Report

Updates the package or adjudication for an existing Report resource.

Use this endpoint to update reports which include the candidate's Social Security Number. To update a Report which does not include an SSN, first use the update Candidate request to add the candidate’s SSN before updating the report.

Either package or adjudication is required.

Note: This endpoint may also be used to update international reports for candidates which do not include an SSN.

Note: The Package of a Report cannot be updated if it has an Adverse Action with the status: complete or dispute. To proceed, cancel the Adverse Action or create a new Report.

Authorizations:
path Parameters
id
required
string

The Report's ID.

Request Body schema: application/json
package
string

Slug of the Package.

adjudication
string
Value: "engaged"

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d package=driver_pro

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "report",
  • "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
  • "status": "complete",
  • "result": "clear",
  • "includes_canceled": false,
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "revised_at": null,
  • "upgraded_at": null,
  • "turnaround_time": 90,
  • "package": "driver_pro",
  • "adjudication": "engaged",
  • "assessment": "eligible",
  • "source": "api",
  • "segment_stamps": [
    ],
  • "work_locations": [
    ],
  • "estimated_completion_time": "2019-07-31T00:00:00Z",
  • "candidate_story_ids": [
    ],
  • "candidate_id": "e44aa283528e6fde7d542194",
  • "drug_screening": {
    },
  • "ssn_trace_id": "539fd88c101897f7cd000001",
  • "arrest_search_id": "539fd88c101897f7cd000001",
  • "drug_screening_id": "539fd88c101897f7cd000001",
  • "facis_search_id": "539fd88c101897f7cd000001",
  • "federal_criminal_search_id": "539fd88c101897f7cd000001",
  • "federal_district_criminal_search_id": "539fd88c101897f7cd000001",
  • "federal_civil_search_id": "539fd88c101897f7cd000001",
  • "federal_district_civil_search_id": "539fd88c101897f7cd000001",
  • "global_watchlist_search_id": "539fd88c101897f7cd000001",
  • "sex_offender_search_id": "539fd88c101897f7cd000008",
  • "national_criminal_search_id": "539fd88c101897f7cd000006",
  • "county_criminal_search_ids": [
    ],
  • "personal_reference_verification_ids": [
    ],
  • "professional_reference_verification_ids": [
    ],
  • "motor_vehicle_report_id": "539fd88c101897f7cd000007",
  • "professional_license_verification_ids": [
    ],
  • "state_criminal_searches": [
    ],
  • "international_criminal_searches_v2_ids": [
    ],
  • "international_adverse_media_search_ids": [
    ],
  • "international_global_watchlist_search_id": "41007c751c9a15c892c0981a0400f3",
  • "international_education_verification_id": "41007c751c9a15c892c0981a040004",
  • "international_employment_verification_id": "41007c751c9a15c892c0981a040015",
  • "international_identity_document_validation_id": "41007c751c9a15c892c0981a040026",
  • "document_ids": [
    ],
  • "geo_ids": [
    ],
  • "program_id": "00166f9ff39ec7b453adfaec"
}

Retrieve an existing Report

Returns an existing Report with the input ID.

Authorizations:
path Parameters
id
required
string

The Report's ID.

query Parameters
include
string

Comma delimited string specifying the resources to be embedded in the returned Report object. See Embedding Resources.

Values include: "arrest_search" "candidate" "candidate_stories" "county_civil_searches" "county_criminal_searches" "credit_report" "dispute_comments" "documents" "drug_screening" "education_verification" "employment_verification" "eviction_search" "facis_search" "federal_civil_search" "federal_criminal_search" "geos" "global_watchlist_search" "international_adverse_media_searches" "international_criminal_searches" "international_criminal_searches_v2" "international_education_verification" "international_employment_verification" "international_global_watchlist_search" "international_identity_document_validation" "motor_vehicle_report" "municipal_criminal_searches" "national_criminal_search" "personal_reference_verifications" "photo_verification" "pointer_state_criminal_searches" "professional_reference_verifications" "professional_license_verifications" "program" "public_comments" "self_disclosures" "sex_offender_search" "ssn_trace" "state_criminal_searches" "terrorist_watchlist_search"
Example: include=candidate,drug_screening

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a?include=drug_screening \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "report",
  • "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
  • "status": "complete",
  • "result": "clear",
  • "includes_canceled": false,
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "revised_at": null,
  • "upgraded_at": null,
  • "turnaround_time": 90,
  • "package": "driver_pro",
  • "adjudication": "engaged",
  • "assessment": "eligible",
  • "source": "api",
  • "segment_stamps": [
    ],
  • "work_locations": [
    ],
  • "estimated_completion_time": "2019-07-31T00:00:00Z",
  • "candidate_story_ids": [
    ],
  • "candidate_id": "e44aa283528e6fde7d542194",
  • "drug_screening": {
    },
  • "ssn_trace_id": "539fd88c101897f7cd000001",
  • "arrest_search_id": "539fd88c101897f7cd000001",
  • "drug_screening_id": "539fd88c101897f7cd000001",
  • "facis_search_id": "539fd88c101897f7cd000001",
  • "federal_criminal_search_id": "539fd88c101897f7cd000001",
  • "federal_district_criminal_search_id": "539fd88c101897f7cd000001",
  • "federal_civil_search_id": "539fd88c101897f7cd000001",
  • "federal_district_civil_search_id": "539fd88c101897f7cd000001",
  • "global_watchlist_search_id": "539fd88c101897f7cd000001",
  • "sex_offender_search_id": "539fd88c101897f7cd000008",
  • "national_criminal_search_id": "539fd88c101897f7cd000006",
  • "county_criminal_search_ids": [
    ],
  • "personal_reference_verification_ids": [
    ],
  • "professional_reference_verification_ids": [
    ],
  • "motor_vehicle_report_id": "539fd88c101897f7cd000007",
  • "professional_license_verification_ids": [
    ],
  • "state_criminal_searches": [
    ],
  • "international_criminal_searches_v2_ids": [
    ],
  • "international_adverse_media_search_ids": [
    ],
  • "international_global_watchlist_search_id": "41007c751c9a15c892c0981a0400f3",
  • "international_education_verification_id": "41007c751c9a15c892c0981a040004",
  • "international_employment_verification_id": "41007c751c9a15c892c0981a040015",
  • "international_identity_document_validation_id": "41007c751c9a15c892c0981a040026",
  • "document_ids": [
    ],
  • "geo_ids": [
    ],
  • "program_id": "00166f9ff39ec7b453adfaec"
}

Complete an existing Report

Cancels all pending or suspended screenings and completes the report.

Use this endpoint to complete reports which include pending or suspended screenings. If a report is completed with pending or suspended screenings, the following events will be triggered:

  • The status for all in-progress screenings within the report will be updated to canceled.
  • A cancellation reason and the reason’s description will be added to each canceled screening.
  • Checkr will issue webhooks upon report completion.
    • If all screenings are canceled, a report.canceled webhook will be issued.
    • If at least one screening has a result before the report is completed, Checkr will issue two webhooks: first, report.updated, followed by report.complete.

Note: This call is available only to those customer accounts which have been updated to the new report lifecycle enhancements. All accounts will be transitioned before the end of 2022. If you wish to enable this functionality for your account before you're scheduled to do so, please reach out to your Checkr Customer Success Manager.

Authorizations:
path Parameters
id
required
string

The Report's ID.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae32a/complete \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "report",
  • "uri": "/v1/reports/4722c07dd9a10c3985ae432a",
  • "status": "complete",
  • "result": "clear",
  • "includes_canceled": false,
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "revised_at": null,
  • "upgraded_at": null,
  • "turnaround_time": 90,
  • "package": "driver_pro",
  • "adjudication": "engaged",
  • "assessment": "eligible",
  • "source": "api",
  • "segment_stamps": [
    ],
  • "work_locations": [
    ],
  • "estimated_completion_time": "2019-07-31T00:00:00Z",
  • "candidate_story_ids": [
    ],
  • "candidate_id": "e44aa283528e6fde7d542194",
  • "drug_screening": {
    },
  • "ssn_trace_id": "539fd88c101897f7cd000001",
  • "arrest_search_id": "539fd88c101897f7cd000001",
  • "drug_screening_id": "539fd88c101897f7cd000001",
  • "facis_search_id": "539fd88c101897f7cd000001",
  • "federal_criminal_search_id": "539fd88c101897f7cd000001",
  • "federal_district_criminal_search_id": "539fd88c101897f7cd000001",
  • "federal_civil_search_id": "539fd88c101897f7cd000001",
  • "federal_district_civil_search_id": "539fd88c101897f7cd000001",
  • "global_watchlist_search_id": "539fd88c101897f7cd000001",
  • "sex_offender_search_id": "539fd88c101897f7cd000008",
  • "national_criminal_search_id": "539fd88c101897f7cd000006",
  • "county_criminal_search_ids": [
    ],
  • "personal_reference_verification_ids": [
    ],
  • "professional_reference_verification_ids": [
    ],
  • "motor_vehicle_report_id": "539fd88c101897f7cd000007",
  • "professional_license_verification_ids": [
    ],
  • "state_criminal_searches": [
    ],
  • "international_criminal_searches_v2_ids": [
    ],
  • "international_adverse_media_search_ids": [
    ],
  • "international_global_watchlist_search_id": "41007c751c9a15c892c0981a0400f3",
  • "international_education_verification_id": "41007c751c9a15c892c0981a040004",
  • "international_employment_verification_id": "41007c751c9a15c892c0981a040015",
  • "international_identity_document_validation_id": "41007c751c9a15c892c0981a040026",
  • "document_ids": [
    ],
  • "geo_ids": [
    ],
  • "program_id": "00166f9ff39ec7b453adfaec"
}

Packages

Packages are a list of screenings to be run for a report. Work with your Checkr Customer Success representative to define Packages that will best serve your business needs.

List existing Packages

Returns a list of all existing Packages.

Authorizations:
query Parameters
page
number Nullable

Specifies the page number to retrieve.

per_page
number Nullable

Indicates how many records each page should contain. The default value is 25 records.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/packages \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{}

Retrieve an existing Package

Returns an existing Package with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Package to retrieve.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/packages \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "package",
  • "uri": "/v1/packages/e44aa283528e6fde7d542194",
  • "created_at": "2014-01-18T12:34:00Z",
  • "deleted_at": "2014-01-18T12:34:00Z",
  • "name": "Criminal Pro",
  • "slug": "criminal_pro",
  • "price": 6500,
  • "screenings": [
    ]
}

Delete an existing Package

Deletes an existing Package.

Authorizations:
path Parameters
id
required
string

ID of the Package to retrieve.

Responses

Request samples

$ curl -X DELETE https://api.checkr.com/v1/packages/e44aa283528e6fde7d542194 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "package",
  • "uri": "/v1/packages/e44aa283528e6fde7d542194",
  • "created_at": "2014-01-18T12:34:00Z",
  • "deleted_at": "2014-01-18T12:34:00Z",
  • "name": "Criminal Pro",
  • "slug": "criminal_pro",
  • "price": 6500,
  • "screenings": [
    ]
}

Invitations

Represents a background check invitation. The candidate will receive an email to submit their information.

Note: By default, the date of expiration is set to 7 days after creation. All invitations expire at 11:59:59pm PDT. This enables candidates to have a full last day to complete their invitation.

Create a new Invitation

Creates a new Invitation resource.

Authorizations:
Request Body schema: application/json
package
required
string

Values dependent on your Account settings.

candidate_id
required
string

ID of the Candidate for whom the Invitation is created.

node
string

Required for hierarchy-enabled accounts.

custom_id of the associated node.

Array of objects (WorkLocation)

Required for hierarchy-enabled accounts.

Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates.

tags
Array of strings

Array of tags for the Report.

communication_types
Array of strings

The means by which candidates will be notified. May be email, sms, or both. If provided, this parameter will override your default account setting for SMS invitations. By including sms in this parameter, you verify that you have recorded your candidate's consent to receive SMS messages.

Items Values include: "email" "sms"

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/invitations \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d candidate_id=e44aa283528e6fde7d542194 \
    -d package=driver_pro \
    -d 'work_locations[][country]=US'

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "invitation",
  • "uri": "/v1/invitations/e44aa283528e6fde7d542194",
  • "status": "pending",
  • "created_at": "2015-05-14T17:45:34Z",
  • "expires_at": "2015-05-21T17:45:34Z",
  • "completed_at": null,
  • "deleted_at": null,
  • "package": "driver_pro",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "report_id": null
}

List existing Invitations

Returns a list of existing Invitations with the input status or candidate_id.

  • If no parameters are passed, returns all Invitations.

  • If candidate_id or status is passed, returns Invitations that match the input parameter.

  • If both candidate_id and status are passed, return Invitations that match both parameters.

Returns 400 if the (optional) status parameter is not pending, expired, or completed. Note: This call will not return invitations with non-US work_locations. Use GET /invitations/{id} to retrieve candidates outside the US.

Authorizations:
query Parameters
candidate_id
string

ID of the candidate to whom the invitation was issued.

status
string

Status of the Invitation.

Values include: "pending" "completed" "expired"
page
number Nullable

Specifies the page number to retrieve.

per_page
number Nullable

Indicates how many records each page should contain. The default value is 25 records.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/invitations \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d status=pending

Response samples

Content type
application/json
{
  • "object": "list",
  • "next_href": "http://example.com",
  • "previous_href": "http://example.com",
  • "count": 2,
  • "data": [
    ]
}

Retrieve an existing Invitation

Returns an existing Invitation with the input ID.

Authorizations:
path Parameters
id
required
string

The Invitation's ID.

query Parameters
include_deleted
boolean

Retrieve an invitation that has been deleted

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/invitations/3c0a0ca94caaab6ca9634f76 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "invitation",
  • "uri": "/v1/invitations/e44aa283528e6fde7d542194",
  • "status": "pending",
  • "created_at": "2015-05-14T17:45:34Z",
  • "expires_at": "2015-05-21T17:45:34Z",
  • "completed_at": null,
  • "deleted_at": null,
  • "package": "driver_pro",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "report_id": null
}

Cancel an existing Invitation

Cancels an existing Invitation.

Authorizations:
path Parameters
id
required
string

The Invitation's ID.

Responses

Request samples

$ curl -X DELETE https://api.checkr.com/v1/invitations/4722c07dd9a10c3985ae432a \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "invitation",
  • "uri": "/v1/invitations/e44aa283528e6fde7d542194",
  • "status": "pending",
  • "created_at": "2015-05-14T17:45:34Z",
  • "expires_at": "2015-05-21T17:45:34Z",
  • "completed_at": null,
  • "deleted_at": null,
  • "package": "driver_pro",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "report_id": null
}

Geos

Represents a candidate geography.

Create a new Geo

Creates a new Geo resource.

Note: Attempting to create a new Geo with the same name/state combination will result in an 409 error

Authorizations:
Request Body schema: application/json
name
required
string

Human-readable name of the Geo.

state
required
string

US state for the Geo.

city
string

A major city within the input state.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/geos \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d name=San+Francisco \
    -d city=San+Francisco \
    -d state=CA

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "geo",
  • "uri": "/v1/geos/e44aa283528e6fde7d542194",
  • "created_at": "2015-01-18T12:34:00Z",
  • "name": "SF CA",
  • "city": "San Francisco",
  • "state": "CA",
  • "deleted_at": null
}

List existing Geos

Returns a list of existing Geos with the input name or state.

Authorizations:
query Parameters
name
string

Returns all Geos with the input name.

state
string

Returns all Geos with the input state.

page
number Nullable

Specifies the page number to retrieve.

per_page
number Nullable

Indicates how many records each page should contain. The default value is 25 records.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/geos \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "object": "list",
  • "next_href": "http://example.com",
  • "previous_href": "http://example.com",
  • "count": 2,
  • "data": [
    ]
}

Retrieve an existing Geo

Returns an existing Geo with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Geo.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/geos/e44aa283528e6fde7d542194 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "geo",
  • "uri": "/v1/geos/e44aa283528e6fde7d542194",
  • "created_at": "2015-01-18T12:34:00Z",
  • "name": "SF CA",
  • "city": "San Francisco",
  • "state": "CA",
  • "deleted_at": null
}

Delete an existing Geo

Deletes an existing Geo.

Authorizations:
path Parameters
id
required
string

ID of the Geo.

Responses

Request samples

$ curl -X DELETE https://api.checkr.com/v1/geos/b719804dc15c655f8529a2f2 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "geo",
  • "uri": "/v1/geos/e44aa283528e6fde7d542194",
  • "created_at": "2015-01-18T12:34:00Z",
  • "name": "SF CA",
  • "city": "San Francisco",
  • "state": "CA",
  • "deleted_at": null
}

Update an existing Geo

Updates an existing Geo resource with the input city. city can only be added once.

Authorizations:
path Parameters
id
required
string

ID of the Geo.

Request Body schema: application/json
city
string Nullable

Updates the Geo with the input city.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/geos/b719804dc15c655f8529a2f2 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d city=San+Francisco

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "geo",
  • "uri": "/v1/geos/e44aa283528e6fde7d542194",
  • "created_at": "2015-01-18T12:34:00Z",
  • "name": "SF CA",
  • "city": "San Francisco",
  • "state": "CA",
  • "deleted_at": null
}

Programs

Represents a division of an Account. Programs are typically used to identify clients, cost centers, or departments. A Program may have many Geos and may have many Packages.

List existing Programs

Returns a list of existing Programs with the input name.

Authorizations:
query Parameters
name
string

Returns Programs with the input name.

page
number Nullable

Specifies the page number to retrieve.

per_page
number Nullable

Indicates how many records each page should contain. The default value is 25 records.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/programs \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "object": "list",
  • "next_href": "http://example.com",
  • "previous_href": "http://example.com",
  • "count": 2,
  • "data": [
    ]
}

Retrieve an existing Program

Returns an existing Program with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Program to retrieve.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/programs/e44aa283528e6fde7d542194 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "program",
  • "name": "Program A",
  • "created_at": "2017-08-07T16:51:09Z",
  • "deleted_at": null,
  • "package_ids": [
    ],
  • "geo_ids": [
    ]
}

Assessments

Use this endpoint to return the Assessments for Reports.

Note: Listen to the report.updated webhook to determine when an Assessment has been applied to a report.

List existing Assessments

Returns Assessments for an existing Report.

Authorizations:
path Parameters
report_id
required
string

The ID of the associated Report.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/reports/b861a56db1b1b89692dd6118/assessments \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "count": 1
}

Subscriptions

Represents a background check subscription. A background report with the Package specified will run at every interval.

Create a new Subscription

Creates a new Subscription.

Note: Subscriptions are not available for reports which include international packages.

Authorizations:
Request Body schema: application/json
package
required
string

Package to run for the Report.

candidate_id
required
string

ID of the candidate being screened.

start_date
required
string <date>

Start date for the subscription. This is the date on which the subscription will begin, and the first time the report will be run.

interval_count
integer

The number of intervals between each recurrent background check.

interval_unit
string

Interval at which the subscription will repeat.

Values include: "day" "week" "month" "year"
node
string

Required for hierarchy-enabled accounts.

custom_id of the associated node.

Array of objects (WorkLocation)

Required for hierarchy-enabled accounts. Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/subscriptions \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d package=driver_pro \
    -d start_date=2017-02-10 \
    -d interval_unit=month \
    -d interval_count=1 \
    -d candidate_id=4722c07dd9a10c3985ae432a

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "subscription",
  • "uri": "/v1/subscriptions/e44aa283528e6fde7d542194",
  • "status": "active",
  • "created_at": "2014-01-18T12:34:00Z",
  • "canceled_at": null,
  • "package": "driver_pro",
  • "interval_count": 1,
  • "interval_unit": "month",
  • "start_date": "2014-06-10",
  • "next_occurrence_date": "2014-07-10",
  • "candidate_id": "4722c07dd9a10c3985ae432a",
  • "node": "zpy8orej4r614ize",
  • "work_locations": [
    ]
}

List existing Subscriptions

Lists existing Subscriptions with the input parameters.

Authorizations:
query Parameters
candidate_id
string

ID of the candidate to search for subscriptions.

created_after
string <date-time>

Returns subscriptions created after the input date.

created_before
string <date-time>

Returns subscriptions created before the input date.

status
string

Returns subscriptions with the input status.

Values include: "active" "inactive"
page
number Nullable

Specifies the page number to retrieve.

per_page
number Nullable

Indicates how many records each page should contain. The default value is 25 records.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/subscriptions \
    -d candidate_id=4722c07dd9a10c3985ae432a
    -d created_after=2021-12-21
    -d created_before=2021-12-31
    -d status=active
    -d page=2
    -d per_page=10

Response samples

Content type
application/json
{
  • "object": "list",
  • "next_href": "http://example.com",
  • "previous_href": "http://example.com",
  • "count": 2,
  • "data": [
    ]
}

Retrieve an existing Subscription

Retrieves an existing Subscription.

Authorizations:
path Parameters
id
required
string

ID of the Subscription.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/subscriptions/e44aa283528e6fde7d542194 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "subscription",
  • "uri": "/v1/subscriptions/e44aa283528e6fde7d542194",
  • "status": "active",
  • "created_at": "2014-01-18T12:34:00Z",
  • "canceled_at": null,
  • "package": "driver_pro",
  • "interval_count": 1,
  • "interval_unit": "month",
  • "start_date": "2014-06-10",
  • "next_occurrence_date": "2014-07-10",
  • "candidate_id": "4722c07dd9a10c3985ae432a",
  • "node": "zpy8orej4r614ize",
  • "work_locations": [
    ]
}

Update a Subscription

Updates a Subscription. Specify only those parameters you wish to change.

Authorizations:
path Parameters
id
required
string

ID of the Subscription.

Request Body schema: application/json
package
string

Package to run for the Report.

candidate_id
string

ID of the candidate being screened.

start_date
string <date>

Start date for the subscription. This is the date on which the subscription will begin, and the first time the report will be run.

interval_count
integer

The number of intervals between each recurrent background check.

interval_unit
string

Interval at which the subscription will repeat.

Values include: "day" "week" "month" "year"
node
string

custom_id of the associated node.

Array of objects (WorkLocation)

Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/subscriptions/e44aa283528e6fde7d542194 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d package=driver_pro \
    -d start_date=2017-02-10 \
    -d interval_unit=month \
    -d interval_count=1 \
    -d candidate_id=e44aa283528e6fde7d542194

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "subscription",
  • "uri": "/v1/subscriptions/e44aa283528e6fde7d542194",
  • "status": "active",
  • "created_at": "2014-01-18T12:34:00Z",
  • "canceled_at": null,
  • "package": "driver_pro",
  • "interval_count": 1,
  • "interval_unit": "month",
  • "start_date": "2014-06-10",
  • "next_occurrence_date": "2014-07-10",
  • "candidate_id": "4722c07dd9a10c3985ae432a",
  • "node": "zpy8orej4r614ize",
  • "work_locations": [
    ]
}

Cancel an existing Subscription

Cancels an existing Subscription.

Authorizations:
path Parameters
id
required
string

ID of the Subscription.

Responses

Request samples

$ curl -X DELETE https://api.checkr.com/v1/subscriptions/e44aa283528e6fde7d542194 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "subscription",
  • "uri": "/v1/subscriptions/4722c07dd9a10c3985ae432a",
  • "status": "active",
  • "created_at": "2014-01-18T12:34:00Z",
  • "canceled_at": "2014-01-30T12:34:00Z",
  • "package": "driver_pro",
  • "interval_count": 1,
  • "interval_unit": "month",
  • "start_date": "2014-06-10",
  • "candidate_id": "e44aa283528e6fde7d542194"
}

Continuous Checks

Continuous Check runs a monthly check for pointers to new records, which may result in a Report. Unlike a Subscription, which generates a full Report at a defined cadence, Continuous Check generates a full Report only if new reportable information is found. For more information, see Continuous Crim: The new standard of safety and Continuous MVR: The new standard in driver safety in the Checkr Help Center.

Use the report.complete webhook to watch for new Reports created for candidates enrolled in Continuous Check. These Reports will list one of the following as the Package within the webhook payload:

  • continuous_check
  • continuous_mvr
  • continuous_mvr_enrollment

Note: These Package names are returned through through the Checkr APIs, but may not be used as input. Attempting to create Invitations, Reports, or Subscriptions with these Packages will result in a Package not found error.

Note: It is your legal obligation to manage your list of candidates enrolled in Continuous Check. You must obtain the required evergreen consent before enrolling them, and you must remove them from the service when they begin an Adverse Action process or are removed from your platform. Work with your legal counsel to ensure that your Continuous Check process remains compliant with all applicable laws and regulations.

Create a new Continuous Check

Creates a new Continuous Check resource.

Authorizations:
path Parameters
candidate_id
required
string

The Candidate's ID.

Request Body schema: application/json
type
required
string

Defines the screening type(s) for this Continuous Check.

Values include: "criminal" "mvr"
node
string

Required for hierarchy-enabled accounts with Nodes.

custom_id of the associated node.

Array of objects (WorkLocation)

Required for hierarchy-enabled accounts.

Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/continuous_checks \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d type=criminal

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "continuous_check",
  • "type": "criminal",
  • "created_at": "2015-05-14T17:45:34Z",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "node": "zpy8orej4r614ize",
  • "work_locations": [
    ]
}

List existing Continuous Checks

Returns a list of existing Continuous Checks.

Authorizations:
path Parameters
candidate_id
required
string

The Candidate's ID.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/continuous_checks \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "count": 1
}

Retrieve an existing Continuous Check

Returns an existing Continuous Check with the input ID.

Authorizations:
path Parameters
id
required
string

The Continuous Check's ID.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/continuous_checks/4722c07dd9a10c3985ae432a \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "continuous_check",
  • "type": "criminal",
  • "created_at": "2015-05-14T17:45:34Z",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "node": "zpy8orej4r614ize",
  • "work_locations": [
    ]
}

Update an existing Continuous Check

Updates the node and/or work locations of an existing Continuous Check.

Authorizations:
path Parameters
id
required
string

The Continuous Check's ID.

Request Body schema: application/json
node
string

custom_id of the associated node.

Array of objects (WorkLocation)

Array of locations described using country, state, and city. When country is not specified defaults to US. State is required for US candidates. Country is required for non-US candidates.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/driver_licenses/76c7435e035d43b55bb9d1c6 \
     -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
     -d node=zpy8orej4r614ize

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "continuous_check",
  • "type": "criminal",
  • "created_at": "2015-05-14T17:45:34Z",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "node": "zpy8orej4r614ize",
  • "work_locations": [
    ]
}

Cancel an existing Continuous Check

Cancels an existing Continuous Check.

Authorizations:
path Parameters
id
required
string

The Continuous Check's ID.

Responses

Request samples

$ curl -X DELETE https://api.checkr.com/v1/continuous_checks/4722c07dd9a10c3985ae432a \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "continuous_check",
  • "type": "criminal",
  • "created_at": "2015-05-14T17:45:34Z",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "node": "zpy8orej4r614ize",
  • "work_locations": [
    ]
}

Adverse Actions

Adverse Actions are initiated by Checkr customers if something is returned on a Candidate’s report that requires further investigation. When an Adverse Action is initiated, the candidate must be informed, and given time to address the issues raised.

National and local laws control the Adverse Action process and define the sequence and timing with which it must process. Please work with your legal council to ensure that your process is compliant.

For more information, see The Adverse Actions Process in the Checkr Help Center.

Retrieve an existing Adverse Action

Returns an existing Adverse Action with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Adverse Action.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/adverse_actions/57ed51e57619e8002a6683f2 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "adverse_action",
  • "uri": "/v1/adverse_actions/57ed51e57619e8002a6683f2",
  • "created_at": "2016-09-29T17:39:49Z",
  • "status": "pending",
  • "report_id": "b861a56db1b1b89692dd6118",
  • "post_notice_scheduled_at": "2016-10-07T12:34:00Z",
  • "post_notice_ready_at": "2016-10-06T17:39:48Z",
  • "canceled_at": null,
  • "adverse_items": [
    ],
  • "individualized_assessment_engaged": false
}

Cancel an existing Adverse Action

Cancels an existing Adverse Action.

Authorizations:
path Parameters
id
required
string

ID of the Adverse Action.

Responses

Request samples

$ curl -X DELETE https://api.checkr.com/v1/adverse_actions/e44aa283528e6fdaa9542194 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "adverse_action",
  • "uri": "/v1/adverse_actions/57ed51e57619e8002a6683f2",
  • "created_at": "2016-09-29T17:39:49Z",
  • "status": "pending",
  • "report_id": "b861a56db1b1b89692dd6118",
  • "post_notice_scheduled_at": "2016-10-07T12:34:00Z",
  • "post_notice_ready_at": "2016-10-06T17:39:48Z",
  • "canceled_at": null,
  • "adverse_items": [
    ],
  • "individualized_assessment_engaged": false
}

Create a new Adverse Action

Creates a new Adverse Action.

Note: Report must be in a consider status and cannot have any existing Adverse Actions that have not been canceled.

Authorizations:
path Parameters
report_id
required
string

The ID of the Report for which the Adverse Action will be created.

Request Body schema: application/json
post_notice_scheduled_at
string <date-time>

Time at which the Post-Adverse Action notification will be sent. Default is 7 days after creation.

adverse_item_ids
required
Array of strings

IDs of Adverse Items selected for the Adverse Action.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/reports/b861a56db1b1b89692dd6118/adverse_actions \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d post_notice_scheduled_at=2016-10-07T12:34:00Z \
    -d 'adverse_item_ids[]=57ed4ce3057e0b002adc6d90&adverse_item_ids[]=57ed4ce3057e0b002adc6d91'

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "adverse_action",
  • "uri": "/v1/adverse_actions/57ed51e57619e8002a6683f2",
  • "created_at": "2016-09-29T17:39:49Z",
  • "status": "pending",
  • "report_id": "b861a56db1b1b89692dd6118",
  • "post_notice_scheduled_at": "2016-10-07T12:34:00Z",
  • "post_notice_ready_at": "2016-10-06T17:39:48Z",
  • "canceled_at": null,
  • "adverse_items": [
    ],
  • "individualized_assessment_engaged": false
}

Adverse Items

Adverse Items are items selected from a returned report that may be used to initiate Adverse Action for a Candidate.

List existing Adverse Items

Returns a list of existing Adverse Items with the input report_id.

Note: Report must be in a consider status and cannot have any existing Adverse Actions that have not been canceled.

Returns 400 if the Report's status is not Consider or the Report already has an active (non-cancelled) Adverse Action.

Authorizations:
path Parameters
report_id
required
string

The ID of the associated Report.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/reports/b861a56db1b1b89692dd6118/adverse_items \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "count": 1
}

Verifications

Represents a link by which candidates may upload a document. If a candidate must upload documents to continue processing their report, a set of Verifications will be available. Checkr offers two verification types: id and education. ID Verifications are used for identity and license purposes, such as ID card or driver’s license. Education Verifications are used for documents related to Education Verification.

List existing Verifications

Returns a list of existing Verifications for the input report_id.

Authorizations:
path Parameters
report_id
required
string

Returns the list of verifications for the input report_id.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/verifications \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "count": 2
}

Retrieve a Verification

Returns an existing Verification with the input ID

Authorizations:
path Parameters
verification_id
required
string

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/verifications/db313e73383710d4fa2f18fd \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "verification",
  • "uri": "/v1/verifications/db313e73383710d4fa2f18fd",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": null,
  • "processed_at": null,
  • "verification_type": "id",
  • "report_id": "4722c07dd9a10c3985ae432a"
}

Documents

Represents a Document, either related to a Report (such as a PDF Report) or related to a Candidate (such as a Driver License image, or a consent form). Report Document IDs can be retrieved from the Retrieve an existing Report endpoint. Candidate Document IDs can be retrieved using the List a Candidate's Documents endpoint.

Use GET /v1/reports/{id}?include=documents to return a Report resource that includes an array of document objects.

Report Documents are of the following types: drug_screen_donor_pass, health_screening_occupational_health_document, health_screening_result_certificate, pdf_credit_report", pdf_health_report, pdf_individualized_assessment, pdf_report, pdf_report_encrypted, pdf_self_disclosure, pdf_wisconsin_doj, and screening_pass.

List a Candidate's Documents

Returns an array of candidate-provided Documents for the input candidate_id.

Authorizations:
path Parameters
candidate_id
required
string

ID of the Candidate for whom documents will be retrieved.

query Parameters
types
Array of strings

The type of candidate-provided document to return. If types is not included in the call, all available Candidate Documents will be returned.

Items Values include: "alien_id" "consent" "citizenship_certificate" "credit_report_consent_form" "driver_license" "driver_license_back" "driver_license_history" "education_proof" "electronic_consent_form" "employment_proof" "government_id" "international_consent_form" "military_id" "national_id" "national_id_back" "passport" "passport_signature_page" "previous_driver_license" "professional_license_certification_image" "selfie" "ssn_card" "state_id_card" "state_id_card_back" "student_id" "taxpayer_id"

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/documents/ \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "count": 1
}

Upload a new Candidate Document

Uploads a new Candidate Document.

Authorizations:
path Parameters
candidate_id
required
string

Upload a document for the input candidate_id.

Request Body schema: multipart/form-data
type
required
string
Values include: "alien_id" "consent" "citizenship_certificate" "credit_report_consent_form" "driver_license" "driver_license_back" "driver_license_history" "education_proof" "electronic_consent_form" "employment_proof" "government_id" "international_consent_form" "military_id" "national_id" "national_id_back" "passport" "passport_signature_page" "previous_driver_license" "professional_license_certification_image" "selfie" "ssn_card" "state_id_card" "state_id_card_back" "student_id" "taxpayer_id"
file
required
string <binary>

Path to the document on your local file system.

Valid MIME types: image/gif, image/jpg, image/jpeg, image/png, image/bmp, image/tiff, application/pdf, image/heic.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/documents \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    --form type=driver_license \
    --form file=@candidate_driver_license.jpg

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "document",
  • "type": "driver_license",
  • "created_at": "2015-02-11T20:01:50Z",
  • "filesize": 8576,
  • "filename": "1423684910_candidate_driver_license.jpg",
  • "content_type": "image/jpeg"
}

Retrieve a Document

Returns an existing Document with the input ID.

Report Document IDs can be retrieved from the Retrieve an existing Report endpoint. Candidate Document IDs can be retrieved using the List a Candidate's Documents endpoint.

Authorizations:
path Parameters
id
required
string

ID of the Document to retrieve.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/documents/b73f89e14b393979857806f9 \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "document",
  • "type": "driver_license",
  • "created_at": "2015-02-11T20:01:50Z",
  • "filesize": 8576,
  • "filename": "1423684910_candidate_driver_license.jpg",
  • "content_type": "image/jpeg"
}

Driver Licenses

The driver licenses resource represents a single driver license for a candidate. Candidates may have one current driver license and may have any number of previous driver licenses.

Create a new Driver License

Creates a new Driver License for a given candidate.

If a current driver license is created for a candidate with an existing driver license marked current, the existing license will be updated to reflect that it is no longer current.

If a candidate_driver_license exists with the state and number passed in with the POST request, a new license will not be created. The current and issued_date values of the existing license will be updated with on the parameters passed.

Note: When a new driver license is created, Checkr will attempt to apply the new license information to resolve any existing exceptions for the candidate's most recent MVR screening if the screening has not yet produced reportable results.

See Driver License validation in the Reference section for a list of valid driver license number input by state.

Authorizations:
path Parameters
candidate_id
required
string

The Candidate's ID.

Request Body schema: application/json
number
required
string

The driver license number.

state
required
string

The state that issued the driver license.

issued_date
string <date>

The issued date of the driver license.

current
required
boolean

Defines whether the driver license is the candidate's current license. true if the license is the candidate's current license, false otherwise.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/driver_licenses \
     -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
     -d number=F2222222 \
     -d state=CA \
     -d issued_date=2010-01-30 \
     -d current=true

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate_driver_license",
  • "uri": "/v1/candidates/551564b7865af96a28b13f36/driver_licenses/e44aa283528e6fde7d542194",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "number": "F2222222",
  • "state": "CA",
  • "issued_dates": [
    ],
  • "current": true
}

List existing Driver Licenses

Returns a list of existing Driver Licenses for the input Candidate ID.

Authorizations:
path Parameters
candidate_id
required
string

The Candidate's ID.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/driver_licenses \
     -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "count": 1
}

Retrieve an existing Driver License

Returns a specific driver license for a given candidate.

Authorizations:
path Parameters
driver_license_id
required
string

The Driver License ID.

candidate_id
required
string

The Candidate's ID.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/driver_licenses/505fe6ed108621f9342c4eff \
     -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate_driver_license",
  • "uri": "/v1/candidates/551564b7865af96a28b13f36/driver_licenses/e44aa283528e6fde7d542194",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "number": "F2222222",
  • "state": "CA",
  • "issued_dates": [
    ],
  • "current": true
}

Update an existing Driver License

Updates an existing Driver License for a given candidate.

Note: Updating an existing license to current: true will set any existing current license to current: false.

Authorizations:
path Parameters
driver_license_id
required
string

The Driver License ID.

candidate_id
required
string

The Candidate's ID.

Request Body schema: application/json
number
string

The updated number of the driver license.

state
string

The updated state that issued the driver license.

issued_date
string <date>

The updated issued date of the driver license.

current
boolean

The updated current status of the driver license. true if the license is the candidate's current license, false otherwise.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/driver_licenses/76c7435e035d43b55bb9d1c6 \
     -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
     -d number=F2222222 \
     -d current=true

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate_driver_license",
  • "uri": "/v1/candidates/551564b7865af96a28b13f36/driver_licenses/e44aa283528e6fde7d542194",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "number": "F2222222",
  • "state": "CA",
  • "issued_dates": [
    ],
  • "current": true
}

Delete an existing Driver License

Deletes a specific driver license for a given candidate.

Authorizations:
path Parameters
driver_license_id
required
string

The Driver License ID.

candidate_id
required
string

The Candidate's ID.

Responses

Request samples

$ curl -X DELETE https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/driver_licenses/505fe6ed108621f9342c4eff \
     -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate_driver_license",
  • "uri": "/v1/candidates/551564b7865af96a28b13f36/driver_licenses/e44aa283528e6fde7d542194",
  • "candidate_id": "551564b7865af96a28b13f36",
  • "number": "F2222222",
  • "state": "CA",
  • "issued_dates": [
    ],
  • "current": true
}

Schools

The School resource includes all relevant educational information for the specified Candidate. School resources are tied to the specified candidate, and do not transfer to other alumna within the system.

Create a new School

Creates a new School resource.

Validation for start_date and end_date is performed to ensure logical dates are provided. end_date must be after start_date, and both dates must be after 1900-01-01.

If the country is not US, the following parameters are required in addition to those marked as required below:

  • year_awarded
  • phone
  • minor
  • start_date
  • end_date
  • current
  • address
    • street
    • city
    • zipcode
    • state
    • country
Authorizations:
path Parameters
candidate_id
required
string

Creates a School for the input candidate_id.

Request Body schema: application/json
candidate_id