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 information about using the Checkr Dashboard, and compliance and regulatory aspects of background checks, visit 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 information about using the Checkr Dashboard, and compliance and regulatory aspects of background checks, visit 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 result update of Clear or Consider through their selected method of API webhooks, email, or Checkr Dashboard notifications.

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

6. Customer evaluates the Report

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

Get credentialed

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

Credentialing and authorizing your account

The background screening industry in the United States is heavily regulated by federal, state, and local levels of government, and primarily by the Fair Credit Reporting Act (FCRA). 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 Requesting a Staging Account in Getting Started.

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

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

Using your API keys

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

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

Keeping your keys safe

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

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

Expiring keys

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

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 is responsible for presenting and capturing all legal disclosure and consent forms and maintaining ongoing compliance with FCRA and state/locality regulations
  • Customer must have adequate legal resources to provide ongoing review of compliance

Checkr Dashboard experience

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

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

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

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

Checkr-hosted candidate experience

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

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

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

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

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

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

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

Self-hosted candidate experience

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

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

Building your candidate experience

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

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

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

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

Compliance and eSignature

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

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

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

The Checkr Dashboard

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.

Request a Staging Account

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

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

Request a staging account

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

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

  2. Topic: enter "Staging account setup request"

  3. Description: Please enter the following information:

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

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

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

Configure your staging account

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

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

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

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

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

Testing Checkr's functions and features

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

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

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

Uses and limitations of the staging account

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

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

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

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.

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

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

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": "complete",
      "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.

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

Retrieve a Report

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

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

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

Retrieve Report response

Retrieve Report response
{
  "id": "a13f4827d8711ddc75abc56ct",
  "object": "report",
  "uri": "/v1/reports/a13f4827d8711ddc75abc56ct",
  "status": "complete",
  "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": [],
  "drug_alcohol_clearinghouse_id": "5b64c62b67abb4002d3ec763",
  "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 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.

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. For more information about setting up webhooks, see the Account Settings article in the Checkr Help Center.

Note: Any webhook URL that fails to accept with a 2XX status code at least one request over a period of 60 days will be removed automatically - e.g. webhooks failing for 100% of the requests during 60 or more days. However if no requests have reached into a webhook URL, over the same period of time, it won't be removed.

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
HTTPS https://(<user>:<password>@)<hostname>/<path>
E.g.: https://notify.company.com/checkr
Notes: The endpoint to be reached must be public.
Webhook URLs 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.

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:

printf "$compact_json" | openssl sha256 -hmac "$PARTNER_APP_CLIENT_SECRET"

In this example, $compact_json is the “non-pretty print” version of a JSON object. For example, you can get the compact version of a json file with the jq tool with: compact_json=$(jq -c < example_response.json).

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

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.

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

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

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": "complete",
      "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.

Form I-9 events

Example I9 Verification event webhook payload
{
  "id": "58f8e550d991bb000db04005",
  "object": "event",
  "type": "formI9.updated",
  "created_at": "2023-11-20T16:44:00Z",
  "data": {
    "object": {
      "id": "c373384e71a9a02098cb7421",
      "object": "formI9",
      "uri": "/v1/i9/forms_i9/e44aa283528e6fde7d542194",
      "candidate_id": "3ae7e278beb24d14a3785e2dd02cca49",
      "event_timestamp": "2023-11-20T16:44:00Z",
      "status": "section_1_completed"
    },
  },
}
Event Description
form_i9.created A new Form I9 has been created.
form_i9.updated A in progress Form I9 has received an update. This update will usually mean a change in the section of the report e.g section 1 is signed by a candidate or employee. It can also mean, for those forms created with a worksite that has E-Verify enabled, a change in the E-Verify status.

You can find information about Form I-9 statuses in the Form I-9 reference section
form_i9.completed A Form I9 has been completed.
form_i9.deleted A Form I9 has been deleted.

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 Continuous checks in the Checkr Help Center.

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

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

Note: if you generate your RSA key via an alternative method, we require a key size of at least 4096 bits for access to production SSN data.

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

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

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

Reference

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: 1200
< 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 1200 requests per minute across all endpoints. We reserve the right to adjust the rate limit for given endpoints.

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

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

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 (wait 2 seconds, then 5, then 10, then 30, etc.) 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.

409 HTTP status code will be received when another request with the same idempotency key is still being processed. Wait for the other request to complete before making a new request with the same idempotency key.

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.

Form I-9 definitions

Workflow types

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

Workflow Type Description
remote_section_1_only Employee will complete Section 1 on their own. Then Employer help them complete Section 2 on-site.
employer_appointment Employee will complete Section 1 on their own. Then Employer authorize a representative to help them complete Section 2.
employee_appointment Employee will complete Section 1 on their own. Then Employer authorize an employee-designated representative to help them complete Section 2.
Form I9 Order Progress

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

Status Description
section_1_incomplete Indicates that the employee must complete Section 1.
section_2_incomplete Indicates that the employer/customer or the Authorized Representative (when applicable) must complete Section 2.
awaiting_approval Indicates that the Authorized Representative has completed Section 2 and the employer/customer must review and approve the I-9.
everify_pending Indicates that the e-Verify process is in progress.
everify_tnc_issued Indicates a Tentative Non-Confirmation (TNC) e-Verify status, which requires action from the employer/customer.
i9_complete Indicates that the I-9/e-Verify process is complete.
Form I9 Open Tasks

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

Status Description
no_action Indicates that there is no action to be taken by the employer/customer.
complete_section_2 Indicates that the employer/customer must complete Section 2.
appoint_section_2_representative Indicates that the employer/customer must appoint an Authorized Representative to complete Section 2.
accept_reject_i9 Indicates that the employer/customer must accept or reject the I-9 after the Authorized Representative has completed Section 2.
check_user_email Indicates that the employer/customer must check the employee's email address as a follow-up action to an e-Verify Tentative Non-Confirmation (TNC) case.

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 New package does not add any screenings
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

Cancellation Reasons

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

Reason Description
candidate_missing_consent Candidate consent not provided
candidate_pii_updated_customer_requested Customer updated candidate PII prior to screening completion
exception_ssn_trace SSN Trace completed with an exception prior to screening completion
source_inaccessible_closed_court Court closed or has limited access to court records
complete_now_customer_requested Customer requested Complete Now prior to screening completion
missing_required_information Required information not received
vendor_unable_to_complete Vendor unable to complete screening
vendor_account_deauthorized Vendor deauthorized account
international_entry_not_supported Screening does not support international entries
no_history_required_information Candidate declared no history
profile_on_hold_customer_requested Customer requested candidate profile on hold
candidate_withdrew_consent Candidate withdrew consent
minors_package_not_enabled Package not configured to allow candidates under age 18
candidate_below_minimum_age Candidate is below the minimum age for a background check
exception_mvr MVR canceled with an exception
customer_account_deauthorized Customer account was deauthorized
adverse_action_completed Adverse Action completed prior to screening completion
adverse_action_suspended_report_timer_customer_requested Customer configured the Adverse Action on Suspended Reports feature and its timer expired prior to screening completion
unable_to_fulfill_mvr Unable to fulfill MVR request as data is not available
identity_verification_unverified Identity Verification completed with an Unverified Result and action was taken to cancel the Report
request_withdrawn Request withdrawn

Verification Types

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

Type
candidate_employment_history
driver_license
driver_license_history
education
id
id_document
license_document
passport_document
previous_license_document
ssn_confirmation
ssn_document
matrix
consent

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",
  • "account_deauthorization": {
    },
  • "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",
  • "segmentation_enabled": true,
  • "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",
  • "account_deauthorization": {
    },
  • "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",
  • "segmentation_enabled": true,
  • "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"
}

Users

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

List existing Users

Returns a list of all existing Users.

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/users \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

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

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.

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": [
    ]
}

Add nodes to a hierarchy

Adds new nodes to an existing Account Hierarchy.

This endpoint creates the nodes synchronously.

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

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/hierarchy/nodes \
    -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
null

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.

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 arranged in order as specified by 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": [
    ]
}

Retrieve an existing node

Returns an existing node by custom_id.

  • If include=packages is passed, 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.
Authorizations:
path Parameters
custom_id
required
string

custom_id of the Node.

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "name": "Acme Staffing",
  • "custom_id": "zpy8orej4r614ize",
  • "tier": "department",
  • "parent_custom_id": "parent custom id",
  • "packages": [
    ]
}

Update an existing node

Updates the name and tier on an existing node by custom_id.

Authorizations:
path Parameters
custom_id
required
string

custom_id of the Node.

Responses

Request samples

$ curl -X PATCH https://api.checkr.com/v1/nodes/my_custom_id \
    -H 'Content-Type: application/json' \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d '{"name":"Acme Staffing", "tier": "department"}'

Response samples

Content type
application/json
{
  • "name": "Acme Staffing",
  • "custom_id": "zpy8orej4r614ize",
  • "tier": "department",
  • "parent_custom_id": "parent custom id",
  • "packages": [
    ]
}

Delete an existing node

Deletes an existing node by custom_id.

Parent nodes and nodes assigned to continuous check subscriptions or legacy subscriptions cannot be deleted.

Authorizations:
path Parameters
custom_id
required
string

custom_id of the Node.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "name": "Acme Staffing",
  • "custom_id": "zpy8orej4r614ize",
  • "tier": "department",
  • "parent_custom_id": "parent custom id",
  • "packages": [
    ]
}

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
string[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[a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]{2,}

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.

postal_address
object

The candidate postal address is the address Checkr will use to send postal mail to the candidate. Each candidate can be associated with only one postal address.

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: \
    -H 'Content-Type: application/json' \
    -d '{"first_name":"John",
        "middle_name":"Alfred",
        "last_name":"Smith",
        "email":"john.smith@gmail.com",
        "phone":"5555555555",
        "zipcode":"90401",
        "dob":"1970-01-22",
        "ssn":"847-43-4645",
        "driver_license_number":"F2111655",
        "driver_license_state":"CA",
        "work_locations":[{"country":"US"}],
        "postal_address": {
                            "name": "John Alfred Smith",
                            "street": "123 Main Street",
                            "street2": "APT A",
                            "city": "San Francisco",
                            "state": "CA",
                            "zipcode": "90401"
                            }
        }'

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",
  • "postal_address": {
    },
  • "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
  • phone
  • 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ªµºÀ-ÖØ-öø-ÿ\-'., ]{2,}

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"
postal_address
object

Candidate's postal address.

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",
  • "postal_address": {
    },
  • "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",
  • "postal_address": {
    },
  • "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",
  • "postal_address": {
    },
  • "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.
  • Employment Verifications, Education Verifications, and Credit Checks may not be initiated using the /reports API. Please use the /invitations API to initiate the Checkr-Hosted Apply Flow when ordering background checks that include any of these screening types.
  • 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

slug of the associated 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_alcohol_clearinghouse_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": [
    ],
  • "occupational_health_screening_id": "539fdcf335644a0ef4000003",
  • "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",
  • "archived": false
}

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_alcohol_clearinghouse_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": [
    ],
  • "occupational_health_screening_id": "539fdcf335644a0ef4000003",
  • "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",
  • "archived": false
}

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_alcohol_clearinghouse" "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" "occupational_health_screening" "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_alcohol_clearinghouse_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": [
    ],
  • "occupational_health_screening_id": "539fdcf335644a0ef4000003",
  • "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",
  • "archived": false
}

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.
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_alcohol_clearinghouse_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": [
    ],
  • "occupational_health_screening_id": "539fdcf335644a0ef4000003",
  • "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",
  • "archived": false
}

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

slug of the associated package.

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.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/invitations \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -H 'Content-Type: application/json' \
    -d '{"candidate_id":"e44aa283528e6fde7d542194",
        "package":"driver_pro",
        "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,
  • "archived": false,
  • "archived_info": {
    }
}

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,
  • "archived": false,
  • "archived_info": {
    }
}

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,
  • "archived": false,
  • "archived_info": {
    }
}

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.

Notes for International Customers: Subscriptions are not available for reports which include international packages. If your candidate is located outside the US, you may not create a Subscription for them.

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

slug of the associated package.

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

Note: If your candidate is located outside of the US, they cannot be enrolled in Continuous Check.

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/continuous_checks/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",
  • "delivery": {
    },
  • "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",
  • "delivery": {
    },
  • "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.

object

The medium through which the Adverse Action notification should be sent.

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'
    -d 'medium={"email": {"priority": 1, "required": true}, "postal": {"priority": 0, "required": false}}'

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "adverse_action",
  • "uri": "/v1/adverse_actions/57ed51e57619e8002a6683f2",
  • "created_at": "2016-09-29T17:39:49Z",
  • "delivery": {
    },
  • "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" "citizenship_certificate" "consent" "credit_report_consent_form" "degree" "diploma" "driver_license" "driver_license_back" "driver_license_history" "education_certificate" "education_proof" "electronic_consent_form" "employment_proof" "government_id" "international_consent_form" "military_id" "national_id" "national_id_back" "passport" "passport_signature_page" "paystub" "previous_driver_license" "professional_license_certification_image" "selfie" "ssn_card" "state_id_card" "state_id_card_back" "student_id" "tax_form1099" "tax_form_schedule_c" "tax_form_w2" "taxpayer_id" "transcript"

Responses

Request samples

curl -X GET https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/documents/ \
     -u 83ebeabdec09f6670863766f792ead24d61fe3f9:
     -d "types[]=driver_license" \
     -d "types[]=consent"

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" "citizenship_certificate" "consent" "credit_report_consent_form" "degree" "diploma" "driver_license" "driver_license_back" "driver_license_history" "education_certificate" "education_proof" "electronic_consent_form" "employment_proof" "government_id" "international_consent_form" "military_id" "national_id" "national_id_back" "passport" "passport_signature_page" "paystub" "previous_driver_license" "professional_license_certification_image" "selfie" "ssn_card" "state_id_card" "state_id_card_back" "student_id" "tax_form1099" "tax_form_schedule_c" "tax_form_w2" "taxpayer_id" "transcript"
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,
  • "source": "Self-Disclosure"
}

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,
  • "source": "Self-Disclosure"
}

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,
  • "source": "Self-Disclosure"
}

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,
  • "source": "Self-Disclosure"
}

Professional Licenses

The professional license resource represents a single certification or license issued to a candidate for qualification in a professional field. Candidates may have two existing professional license resources at a time.

Create a new Professional License

Creates a new Professional License for a given candidate. A maximum of two licenses may exist for each candidate. When a report is run with Professional License Verification, all candidate licenses existing at the time of report creation will be included for verification.

Authorizations:
path Parameters
candidate_id
required
string

The Candidate's ID

Request Body schema: application/json
expiration_date
required
string <date>

Expiration date of the professional license

issuer_name
required
string

Name of the organization that issued the professional license

issuer_region
required
string

2-letter abbreviation of US state where license was issued. For licenses not issued for a specific state, use "United States".

license_type
required
string

Category or industry of professional license

license_number
string

Unique identifier assigned to license by issuer. Format may vary

certification_document_id
required
string

ID of document previously created with the uploadDocument endpoint. Document must be of type professional_license_certification_image and should contain an image proof of professional license to be verified.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/candidates/5fb31d36bc2e7f4609aba03d/professional_licenses \
     -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
     -d expiration_date=2033-01-30 \
     -d issuer_name='Medical Board of California' \
     -d issuer_region=CA \
     -d license_number=A12345 \
     -d license_type=Physician \
     -d certification_document_id=4a3e270ccecdd1455d9f4685

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "expiration_date": "2033-01-30",
  • "issuer_name": "Medical Board of California",
  • "issuer_region": "CA",
  • "license_type": "Physician",
  • "license_number": "A 12345"
}

List existing Professional Licenses

Returns a list of existing Professional Licenses for the given Candidate ID.

Authorizations:
path Parameters
candidate_id
required
string

The Candidate's ID

Responses

Request samples

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

Response samples

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

Delete an existing Professional License

Deletes an existing Professional License

Authorizations:
path Parameters
candidate_id
required
string

The Candidate's ID

license_id
required
string

The ID of the license to delete.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "expiration_date": "2033-01-30",
  • "issuer_name": "Medical Board of California",
  • "issuer_region": "CA",
  • "license_type": "Physician",
  • "license_number": "A 12345",
  • "deleted_at": "2023-10-10T01:16:27.000Z"
}

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
string non-empty [a-zA-Z0-9 -'.,]*

Candidate linked to this School resource.

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

Name of the School.

degree
required
string

Degree awarded to the Candidate.

year_awarded
integer non-empty

Year in which the degree was awarded.

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

Candidate’s major.

phone
string Nullable

School's phone number.

minor
string

Candidate’s minor.

start_date
string <date>

Candidate’s start date with the School.

end_date
string <date>

Candidate’s end date with the School.

current
boolean
Default: false

Defines whether the Candidate is currently enrolled.

school_url
string

School’s website.

required
object (Address)

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/schools \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d name=College\ University \
    -d address\[street\]=1+Circle+Avenue \
    -d address\[city\]=San+Francisco \
    -d address\[zipcode\]=94105 \
    -d address\[state\]=CA \
    -d address\[country\]=US \
    -d degree=BS \
    -d year_awarded=2017 \
    -d major=Computer+Science \
    -d phone=111-111-1111 \
    -d minor=Background+Checks \
    -d start_date=2012-09-25 \
    -d end_date=2017-05-29 \
    -d current=false \
    -d school_url=www.school.com

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "school",
  • "uri": "/v1/schools/e44aa283528e6fde7d542194",
  • "candidate_id": "83ebeagdec0948690863766f792ead24d61fe3f9",
  • "name": "College University",
  • "degree": "BA",
  • "year_awarded": 2017,
  • "major": "Russian Literature",
  • "phone": "415-111-1111",
  • "minor": "Background Checks",
  • "start_date": "2012-09-22",
  • "end_date": "2017-05-10",
  • "current": false,
  • "school_url": "www.collegeuniversity.com",
  • "address": {
    }
}

List existing Schools

Returns a list of existing Schools for the input candidate_id.

Authorizations:
path Parameters
candidate_id
required
string

Returns the list of schools for the input candidate_id.

Responses

Request samples

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

Response samples

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

Delete an existing School

Deletes an existing School with the input school_id.

Authorizations:
path Parameters
id
required
string

The School's ID.

candidate_id
required
string

The Candidate's ID.

Responses

Request samples

$ curl -X DELETE https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/schools/95a95172bb81143ed44e403c \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "school",
  • "uri": "/v1/schools/e44aa283528e6fde7d542194",
  • "candidate_id": "83ebeagdec0948690863766f792ead24d61fe3f9",
  • "name": "College University",
  • "degree": "BA",
  • "year_awarded": 2017,
  • "major": "Russian Literature",
  • "phone": "415-111-1111",
  • "minor": "Background Checks",
  • "start_date": "2012-09-22",
  • "end_date": "2017-05-10",
  • "current": false,
  • "school_url": "www.collegeuniversity.com",
  • "address": {
    }
}

Retrieve an existing School

Returns an existing School with the input school_id.

Authorizations:
path Parameters
id
required
string

The School's ID.

candidate_id
required
string

The Candidate's ID.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "school",
  • "uri": "/v1/schools/e44aa283528e6fde7d542194",
  • "candidate_id": "83ebeagdec0948690863766f792ead24d61fe3f9",
  • "name": "College University",
  • "degree": "BA",
  • "year_awarded": 2017,
  • "major": "Russian Literature",
  • "phone": "415-111-1111",
  • "minor": "Background Checks",
  • "start_date": "2012-09-22",
  • "end_date": "2017-05-10",
  • "current": false,
  • "school_url": "www.collegeuniversity.com",
  • "address": {
    }
}

Employers

The Employers resource includes all relevant employer information for the specified Candidate. Employer resources are tied to the specified candidate, and do not transfer to other employees within the system. Once attached to a candidate, all employers are retained when running subsequent employment verifications. For example, if multiple employment verifications are run for an existing candidate, each report will use all employers attached to that candidate for the verification.

Create a new Employer

Creates a new Employer resource.

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

  • salary
  • address:
    • street
    • country
    • zipcode
  • manager:
    • name
    • title

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.

Authorizations:
path Parameters
candidate_id
required
string

Create an employer for the input candidate_id.

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

ID of the Candidate being screened.

type
string
Default: "employer"

Type of employment history to be created.

If type is set to gap only start_date is required, and only start_date, end_date, and note will be recorded.

Values include: "employer" "gap"
name
required
string non-empty [a-zA-Z0-9 -'.,]*

Candidate’s employer’s name.

position
required
string

Candidate’s position or title.

salary
integer

Candidate’s gross salary in dollars annually.

contract_type
required
string

Candidate’s contract type.

Values include: "full_time" "part_time" "contract" "internship"
do_not_contact
boolean
Default: false

If true, the employer will not be contacted about the Candidate.

start_date
required
string <date>

Candidate’s start date with the employer.

end_date
string <date>

Candidate’s end date with the employer.

employer_url
string

Employer’s website.

required
object (Address)
object
note
string <= 65535 characters

A text note used to add context for an employment gap.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/employers \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d name=Checkr \
    -d position=Engineer \
    -d salary=10000 \
    -d address\[street\]=123+Main+St. \
    -d address\[city\]=San+Francisco \
    -d address\[state\]=CA \
    -d address\[zipcode\]=94108 \
    -d address\[country\]=US \
    -d contract_type=full_time \
    -d start_date=2016-01-22 \
    -d end_date=2017-01-22 \
    -d manager\[name\]=Joe \
    -d manager\[title\]=Manager \
    -d employer_url=www.employer.com

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "employer",
  • "uri": "/v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda",
  • "candidate_id": "xxx",
  • "name": "Checkr",
  • "position": "Software Engineer",
  • "salary": 10000,
  • "contract_type": "full_time",
  • "do_not_contact": false,
  • "start_date": "2016-06-01",
  • "end_date": "2017-05-01",
  • "employer_url": "www.employer.com",
  • "address": {
    },
  • "manager": {
    }
}

List existing Employers

Returns a list of existing Employers for the input candidate_id.

Authorizations:
path Parameters
candidate_id
required
string

Returns the list of employers for the input candidate_id.

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/candidates/e44aa283528e6fde7d542194/employers \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

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

Delete an existing Employer

Deletes an existing Employer with the input id.

Authorizations:
path Parameters
employer_id
required
string

The Employer's ID.

candidate_id
required
string

The Candidate's ID.

Responses

Request samples

$ curl -X DELETE https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/employers/95a95172bb81143ed44e403c \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "employer",
  • "uri": "/v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda",
  • "candidate_id": "xxx",
  • "name": "Checkr",
  • "position": "Software Engineer",
  • "salary": 10000,
  • "contract_type": "full_time",
  • "do_not_contact": false,
  • "start_date": "2016-06-01",
  • "end_date": "2017-05-01",
  • "employer_url": "www.employer.com",
  • "address": {
    },
  • "manager": {
    }
}

Retrieve an existing Employer

Returns an existing Employer with the input candidate_id or employer_id.

Authorizations:
path Parameters
employer_id
required
string

The Employer's ID.

candidate_id
required
string

The Candidate's ID.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "employer",
  • "uri": "/v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda",
  • "candidate_id": "xxx",
  • "name": "Checkr",
  • "position": "Software Engineer",
  • "salary": 10000,
  • "contract_type": "full_time",
  • "do_not_contact": false,
  • "start_date": "2016-06-01",
  • "end_date": "2017-05-01",
  • "employer_url": "www.employer.com",
  • "address": {
    },
  • "manager": {
    }
}

Counties

The Counties resource provides a list of all counties within the United States. Use the returned list to validate the counties submitted by your candidates during the Self Disclosure process.

Get Counties by State(s)

Returns a list of all counties for the input state(s). If no state is provided with the query, returns a list of all counties in the United States.

Authorizations:
query Parameters
states
string

A comma-separated list of states' Federal Information Processing Series (FIPS) values to query.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/counties?states=HI \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "HI": {
    }
}

Report Tags

Report Tags are defined by customers, and may be used to search Reports.

Add a tag to a Report

This request is used to add a tag to a Report.

Note: The tag value passed to POST /v1/reports/{id}/tags will match the name field in the response.

Authorizations:
path Parameters
id
required
string

The Report's ID.

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.

Request Body schema: application/json
tag
required
string

Responses

Request samples

curl -X POST https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/tags \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d tag=In+Progress

Response samples

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

Update tags for a Report

This request is used to define all tags for a Report.

Authorizations:
path Parameters
id
required
string

The Report's ID.

Request Body schema: application/json
tags
required
Array of strings

Responses

Request samples

curl -X PUT https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/tags \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d tags[]=West+Coast \
    -d tags[]=To+Review

Response samples

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

Retrieve tags for a Report

Retrieves tags for the input Report.

Authorizations:
path Parameters
id
required
string

The Report's ID.

Responses

Request samples

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

Response samples

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

Delete a tag from a Report

This request is used to delete a tag from a Report.

Authorizations:
path Parameters
id
required
string

The Report's ID.

Request Body schema: application/json
tag
required
string

Responses

Request samples

curl -X DELETE https://api.checkr.com/v1/reports/4722c07dd9a10c3985ae432a/tags \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d tag=West+Coast

Response samples

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

Report Addresses

Represents candidate reported addresses on a Report.

List existing Report addresses

This request is used to retrieve addresses for a given Report.

Authorizations:
path Parameters
report_id
required
string

Returns the list of Report addresses for the input report_id.

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/reports/4722c07dd9a10c3985ae432a/addresses \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

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

Report ETA

Report ETAs predict when screenings will complete for each background check report. This ETA provides a date for the estimated completion of a specific report, helping both you and your candidates plan ahead.

While the predictions are highly accurate, they are not a guarantee. Some county-level searches are subject to unpredictable timelines, due to manual search processes and court availability. For more information on these searches, please see County Criminal Record Search in the Checkr Help Center.

90% of reports will complete within one business day of the estimated date.

For those reports which do not complete within the initial estimate, Checkr will re-generate the ETA using the current information available for the remaining screenings. A report.updated webhook will be issued for both the initial and each subsequent ETA.

For more information, see Checkr ETA in the Checkr Help Center.

Retrieve a Report's ETA

Returns an existing Report ETA for the input Report ID.

Authorizations:
path Parameters
id
required
string

ID of the Report for which the ETA was generated.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "estimate_generated_at": "2014-01-18T12:34:00Z",
  • "estimated_completion_time": "2019-07-31T00:00:00Z"
}

Candidate Stories

Candidate Stories allows candidates with records the opportunity to share additional context about themselves and their background checks. Once submitted, these stories will be available to customers in the candidate’s report in the Checkr Dashboard.

For more information, please see Candidate Stories: Improving understanding of the past and present in the Checkr Help Center.

Retrieve a Candidate Story

Returns the existing Candidate Story corresponding to the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Candidate Story.

Responses

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate_story",
  • "uri": "/v1/candidate_stories/e44aa283528e6fde7d542194",
  • "report_id": "af3393b7d751206c7c67b6e5",
  • "record": {
    },
  • "content": "Since my case, I have received the following certifications (see attachments)",
  • "created_at": "2020-04-17T07:48:34Z",
  • "documents": [
    ]
}

Delete a Candidate Story

Deletes the existing Candidate Story corresponding to the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Candidate Story.

Responses

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate_story",
  • "uri": "/v1/candidate_stories/e44aa283528e6fde7d542194",
  • "report_id": "af3393b7d751206c7c67b6e5",
  • "record": {
    },
  • "content": "Since my case, I have received the following certifications (see attachments)",
  • "created_at": "2020-04-17T07:48:34Z",
  • "documents": [
    ]
}

Create a new Candidate Story

Create a new Candidate Story for the input report_id.

Authorizations:
path Parameters
report_id
required
string

Create an candidate story for the input report_id.

Request Body schema: application/json
content
required
string

Additional information provided by Candidate.

record_id
string

ID of the Record existing on a Screening to which the Candidate Story is linked. When no record ID is provided, the Candidate Story is considered General Information.

required
Array of objects

An array of documents to attach to the Candidate Story. Can be empty.

Responses

Request samples

Content type
application/json
{
  • "content": "Since my case, I have received the following certifications (see attachments)",
  • "record_id": "af3393b7d751206c7c67b6e5",
  • "documents": []
}

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate_story",
  • "uri": "/v1/candidate_stories/e44aa283528e6fde7d542194",
  • "report_id": "af3393b7d751206c7c67b6e5",
  • "record": {
    },
  • "content": "Since my case, I have received the following certifications (see attachments)",
  • "created_at": "2020-04-17T07:48:34Z",
  • "documents": [
    ]
}

SSN

The SSN resource allows you to retrieve a candidate's encrypted SSN.

Note: Access to this endpoint requires an RSA key-pair for encryption. See Configuring Encryption for Candidate SSN Endpoint for information on how to generate encryption keys. Work with your Checkr Customer Success Manager to enable this feature for your account.

Get a candidate's encrypted SSN

Returns an encrypted SSN 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/e44aa283528e6fde7d542194/ssn/ \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "encrypted_ssn": "hyYMhDje9dVUEPKU9myy7OFJ7R27pj0pmlegFlka99I="
}

Webhooks

Use webhooks to receive updates on objects created with the API and to kick off additional workflows based on these events. See Webhooks for more information.

Create a new Webhook

Creates a new Webhook resource. An account can have a maximum of 2 webhooks.

Any webhook URL that fails to accept with a 2XX status code at least one request over a period of 60 days will be removed automatically - e.g. webhooks failing for 100% of the requests during 60 or more days.

Authorizations:
Request Body schema: application/json
include_object
boolean

When true, the webhook event payload will include the related object.

webhook_url
required
string

The URL which receives the webhook event payload. This must be an HTTPS or an AWS SNS URL. For more information, see Supported Webhook URLs section.

live
boolean

When 'true', the webhook is for the live environment.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/webhooks \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d include_object=true \
    -d webhook_url=https://example.com

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "webhook",
  • "uri": "/v1/webhooks/e44aa283528e6fde7d542194",
  • "account_id": "8e122cc56b8fa82d33c6118a",
  • "application_id": null,
  • "include_object": true,
  • "webhook_url": "https://example.com",
  • "created_at": "1939-09-01T12:21:00Z",
  • "deleted_at": null
}

List existing Webhooks

Returns a list of existing Webhooks

Authorizations:

Responses

Request samples

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

Response samples

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

Retrieve a Webhook

Returns the existing Webhook corresponding to the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Webhook.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "webhook",
  • "uri": "/v1/webhooks/e44aa283528e6fde7d542194",
  • "account_id": "8e122cc56b8fa82d33c6118a",
  • "application_id": null,
  • "include_object": true,
  • "webhook_url": "https://example.com",
  • "created_at": "1939-09-01T12:21:00Z",
  • "deleted_at": null
}

Delete a Webhook

Deletes the existing Webhook corresponding to the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Webhook.

Responses

Request samples

curl -X DELETE https://api.checkrhq-staging.net/v1/webhooks/e44aa283528e6fde7d542194 \
     -u 83ebeabdec09f6670863766f792ead24d61fe3f9:

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "webhook",
  • "uri": "/v1/webhooks/e44aa283528e6fde7d542194",
  • "account_id": "8e122cc56b8fa82d33c6118a",
  • "application_id": null,
  • "include_object": true,
  • "webhook_url": "https://example.com",
  • "created_at": "1939-09-01T12:21:00Z",
  • "deleted_at": "1945-09-02T04:40:00Z"
}

Candidate Postal Address

The candidate postal address is the address Checkr will use to send postal mail to the candidate. Each candidate can be associated with only one postal address.

Get the Candidate's Postal Addresses

Returns the Postal Address of a given candidate.

Authorizations:
path Parameters
candidate_id
required
string

The candidate's ID.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate_postal_address",
  • "candidate_id": "e44aa283528e6fde7d542194",
  • "uri": "/v1/candidate/e44aa283528e6fde7d542194/postal_address",
  • "name": "John Alfred Smith",
  • "street": "123 Main St",
  • "street2": "Apt A",
  • "city": "Santa Monica",
  • "state": "CA",
  • "zipcode": "90401"
}

Create a new Postal Address

Creates a new Postal Address for a given candidate.

Authorizations:
path Parameters
candidate_id
required
string

The candidate's ID.

Request Body schema: application/json
name
required
string

Name of the Candidate.

street
required
string

Street address of the Candidate.

street2
string Nullable

Additional street address of the Candidate.

city
required
string

City of the Candidate.

state
required
string

State of the Candidate.

zipcode
required
string

5-digit zip code of the Candidate.

Responses

Request samples

curl -X POST https://api.checkr.com/v1/candidates/e44aa283528e6fde7d542194/postal_address \
    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \
    -d '{
            "name": "John Alfred Smith",
            "street": "123 Main Street",
            "street2": "APT A",
            "city": "San Francisco",
            "state": "CA",
            "zipcode": "94108"
        }'

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "candidate_postal_address",
  • "candidate_id": "e44aa283528e6fde7d542194",
  • "uri": "/v1/candidate/e44aa283528e6fde7d542194/postal_address",
  • "name": "John Alfred Smith",
  • "street": "123 Main St",
  • "street2": "Apt A",
  • "city": "Santa Monica",
  • "state": "CA",
  • "zipcode": "90401"
}

SSN Trace

SSN Trace is typically the first screening run, and is used to verify that the input SSN exists, determine where and when it was issued, and to compile a list of all known aliases associated with the SSN. This Trace is also used to generate a list of all known addresses recorded by credit agencies for the SSN for the last 7 years.

An SSN Trace may be used to determine which additional jurisdictions should be searched for the candidate, based on the list of known addresses returned.

If the platform detects an issue with the SSN Trace run (data mismatch, absence of data, or inclusion of the SSN on the death master file), Checkr may issue an exception and ask the candidate to either re-enter their SSN or upload other supporting documentation.

Note: Information returned by this search is not a part of the consumer report and may not be used for FCRA purposes, including eligibility determinations under the FCRA

For more information, please see SSN Trace in the Checkr Help Center.

Retrieve an existing SSN Trace

Returns an existing SSN Trace with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the SSN Trace to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "ssn_trace",
  • "uri": "/v1/ssn_traces/539fd88c101897f7cd000001",
  • "status": "complete",
  • "result": null,
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": null,
  • "cancellation_reason_description": null,
  • "ssn": "XXX-XX-4645",
  • "no_data": false,
  • "dob_mismatch": false,
  • "name_mismatch": false,
  • "data_mismatch": false,
  • "thin_file": false,
  • "invalid_issuance_year": false,
  • "death_index": false,
  • "ssn_already_taken": false,
  • "issued_year": 1993,
  • "issued_state": "CA",
  • "addresses": [ ],
  • "aliases": [ ]
}

Retrieve an existing Sex Offender Registry Search

Returns an existing Sex Offender Registry Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Sex Offender Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "sex_offender_search",
  • "uri": "/v1/sex_offender_searches/539fd88c101897f7cd000008",
  • "status": "complete",
  • "result": "consider",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "records": [
    ]
}

Retrieve an existing Global Watchlist Search

Returns an existing Global Watchlist Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Global Watchlist Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "global_watchlist_search",
  • "uri": "/v1/global_watchlist_searches/539fd88c101897f7cd000008",
  • "status": "complete",
  • "result": "consider",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "records": [
    ]
}

Retrieve an existing National Criminal Search

Returns an existing National Criminal Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the National Criminal Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "national_criminal_search",
  • "uri": "/v1/national_criminal_searches/539fd88c101897f7cd000006",
  • "status": "complete",
  • "result": null,
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": null,
  • "cancellation_reason_description": null,
  • "records": [
    ]
}

Retrieve an existing Federal Criminal Search

Returns an existing Federal Criminal Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Federal Criminal Search to retrieve.

query Parameters
exclude
string

Indicates whether to return disctrict screenings in pointer search payload

Example: exclude=district

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "federal_criminal_search",
  • "uri": "/v1/federal_criminal_searches/539fd88c101897f7cd000006",
  • "status": "complete",
  • "result": "clear",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": null,
  • "cancellation_reason_description": null,
  • "assessment": "eligible",
  • "records": [
    ],
  • "filtered_by_positive_adjudication_records": [
    ]
}

Retrieve an existing Federal District Criminal Search

Returns an existing Federal District Criminal Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Federal District Criminal Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "federal_district_criminal_search",
  • "uri": "/v1/federal_district_criminal_searches/625487abdc27f729a9997f50",
  • "status": "complete",
  • "result": "clear",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "records": [
    ],
  • "records_hidden_by_assess": [
    ],
  • "filtered_by_positive_adjudication_records": [
    ]
}

Retrieve an existing Federal Civil Search

Returns an existing Federal Civil Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Federal Civil Search to retrieve.

query Parameters
exclude
string

Indicates whether to return district screenings in pointer search payload

Example: exclude=district

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "federal_civil_search",
  • "uri": "/v1/federal_civil_searches/625487abdc27f729a9997f50",
  • "status": "complete",
  • "result": "clear",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": null,
  • "cancellation_reason_description": null,
  • "records": [
    ],
  • "records_hidden_by_assess": [
    ],
  • "filtered_by_positive_adjudication_records": [
    ]
}

Retrieve an existing Federal District Civil Search

Returns an existing Federal District Civil Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Federal District Civil Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "federal_district_civil_search",
  • "uri": "/v1/federal_district_civil_searches/625487abdc27f729a9997f50",
  • "status": "complete",
  • "result": "clear",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "records": [
    ],
  • "records_hidden_by_assess": [
    ],
  • "filtered_by_positive_adjudication_records": [
    ]
}

Retrieve an existing County Criminal Search

Returns an existing County Criminal Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the County Criminal Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "county_criminal_search",
  • "uri": "/v1/county_criminal_searches/539fdcf335644a0ef4000001",
  • "status": "complete",
  • "result": "consider",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 100800,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "estimated_completion_time": "2019-03-13T16:31:07Z",
  • "estimated_completion_date": "2019-03-13",
  • "county": "SAN FRANCISCO",
  • "state": "CA",
  • "records": [
    ],
  • "filtered_by_positive_adjudication_records": [
    ],
  • "screening_pointers": [
    ]
}

Retrieve an existing State Criminal Search

Returns an existing State Criminal Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the State Criminal Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "state_criminal_search",
  • "uri": "/v1/state_criminal_searches/539fdcf335644a0ef4000001",
  • "status": "complete",
  • "result": "consider",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 100800,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "estimated_completion_time": "2014-01-18T12:34:00Z",
  • "state": "CA",
  • "records": [
    ],
  • "filtered_by_positive_adjudication_records": [
    ],
  • "screening_pointers": [
    ]
}

Motor Vehicle Report

Motor Vehicle Records originate from a state’s Department of Motor Vehicles, and include information related to a person’s driving history, including driver’s license status and restrictions, as well as violations and convictions. Use MVR reports to evaluate a candidate’s driving history and safety record.

Please note that some convictions, such as driving under the influence, may appear only on MVR reports, and not on criminal searches.

For more information, please see Motor Vehicle Records in the Checkr Help Center.

Retrieve an existing Motor Vehicle Report

Returns an existing Motor Vehicle Report with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Motor Vehicle Report to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "motor_vehicle_report",
  • "uri": "/v1/motor_vehicle_reports/539fd88c101897f7cd000007",
  • "status": "complete",
  • "result": "consider",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "license_reports": [
    ],
  • "full_name": "John Alfred Smith",
  • "license_number": "F2111132",
  • "license_state": "CA",
  • "previous_license_number": "F2111132",
  • "previous_license_state": "CA",
  • "license_status": "valid, expired, not_found",
  • "license_type": "personal, commercial, or non-commercial",
  • "license_class": "C",
  • "dob": "1980-01-01",
  • "expiration_date": "2016-07-24",
  • "covid_extension": true,
  • "issued_date": "2006-12-03",
  • "first_issued_date": "2000-01-14",
  • "inferred_issued_date": null,
  • "restrictions": [
    ],
  • "custom_rules": {
    },
  • "not_found": false,
  • "experience_failed": false,
  • "type": "standard",
  • "privilege_to_drive": "valid",
  • "accidents": [
    ],
  • "violations": [
    ],
  • "suspensions": [
    ]
}

Retrieve an existing Drug & Alcohol Clearinghouse Search

Returns an existing Drug & Alcohol Clearinghouse Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Drug & Alcohol Clearinghouse Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "report_id": "539fd88c101897f7cd000007",
  • "query_result": "Driver Not Prohibited",
  • "status": "complete",
  • "cancellation_reason": "candidate_missing_consent",
  • "cancellation_reason_description": "Candidate consent not provided"
}

Education Verification

Use an Education Verification to verify a candidate’s education history, and highest degree achieved.

For this screening, candidates are asked to supply their degree, major, school, and the state in which the school is located. Checkr then attempts to verify the information. After three failed attempts (itemized in the logs), Checkr generates an exception, and asks the candidate to upload supporting documentation. Once the document is uploaded, the verification process will begin again.

For more information, please see Education Verification in the Checkr Help Center.

Retrieve an existing Education Verification

Returns an existing Education Verification with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Education Verification to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "education_verification",
  • "uri": "/v1/education_verifications/595511af261066005170f47",
  • "status": "consider",
  • "result": "consider",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 603216,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "includes_canceled": true,
  • "records": [
    ]
}

Employment Verification

Use an Employment Verification to verify a candidate’s employment history for the last three employers, or the last seven years.

For this screening, candidates are asked to supply their employment history. Checkr then attempts to verify the information. After three failed attempts (itemized in the logs), Checkr generates an exception, and asks the candidate to upload supporting documentation. Once the document is uploaded, the verification process will begin again.

For more information, please see Employment Verification in the Checkr Help Center.

Retrieve an existing Employment Verification

Returns an existing Employment Verification with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Employment Verification to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "employment_verification",
  • "uri": "/v1/employment_verifications/595511af261066005170f471",
  • "status": "consider",
  • "result": "consider",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 603216,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "includes_canceled": true,
  • "records": [
    ]
}

Personal Reference Verification

Use a Personal Reference Verification to verify a candidate’s personal credentials. For this screening, candidates are asked to supply a personal reference. Checkr then contacts the personal reference and asks predefined questions to confirm their credentials. For more information, please see Personal and Professional Reference Checks.

Retrieve an existing Personal Reference Verification

Returns an existing Personal Reference Verification with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Personal Reference Verification to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "642f279b0ea616002e474daa",
  • "object": "personal_reference_verifications",
  • "uri": "/v1/personal_reference_verifications/642f279b0ea616002e474daa",
  • "status": "consider",
  • "result": "consider",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 42,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "name": "John Smith",
  • "email": "john.smith@gmail.com",
  • "phone": 5555555555,
  • "relationship": "Friend",
  • "questions": [
    ]
}

Professional Reference Verification

Use a Professional Reference Verification to verify a candidate’s professional credentials. For this screening, candidates are asked to supply a professional reference. Checkr then contacts the professional reference and asks predefined questions to confirm their credentials. For more information, please see Personal and Professional Reference Checks.

Retrieve an existing Professional Reference Verification

Returns an existing Professional Reference Verification with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Professional Reference Verification to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "642f279b0ea616002e474daa",
  • "object": "professional_reference_verifications",
  • "uri": "/v1/professional_reference_verifications/642f279b0ea616002e474daa",
  • "status": "consider",
  • "result": "consider",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 42,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "name": "John Smith",
  • "email": "john.smith@gmail.com",
  • "phone": 5555555555,
  • "relationship": "Manager",
  • "questions": [
    ]
}

Professional License Verification

Use a Professional License Verification to verify a candidate's professional credentials.

Retrieve an existing Professional License Verification

Returns an existing Professional License Verification with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Professional License Verification to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "e44aa283528e6fde7d542194",
  • "object": "professional_license_verification",
  • "uri": "/v1/professional_license_verifications/5ee1b0c080c74df951ce6a59",
  • "status": "consider",
  • "result": "consider",
  • "assessment": "eligible",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 603216,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "documents": [
    ],
  • "certifications": [
    ]
}

Retrieve an existing International Adverse Media Search

Returns an existing International Adverse Media Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the International Adverse Media Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "41007cffefb435cf7d701f75d8b86c",
  • "object": "international_adverse_media_search",
  • "uri": "/v1/international_adverse_media_searches/41007cffefb435cf7d701f75d8b86c",
  • "status": "complete",
  • "result": "clear",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "country": "FR",
}

Retrieve an existing International Criminal Search

Returns an existing International Criminal Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the International Criminal Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "41007cffefb435cf7d701f75d8b86d",
  • "object": "international_criminal_search",
  • "uri": "/v1/international_criminal_searches/41007cffefb435cf7d701f75d8b86d",
  • "status": "complete",
  • "result": "clear",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "records": [
    ],
  • "country": "FR",
}

International Education Verification

The verification of academic status of any educational level such as high school, college and post-grad may include institution name, dates of attendance, graduation/conferred date, degree obtained, major, minor, honors and relevant awards. Reasonable attempts will be made to search available industry databases and international educational institutions. Refer to International Screenings for more details.

Retrieve an existing International Education Verificaiton

Returns an existing International Education Verificaiton with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the International Education Verificaiton to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "41007cffefb435cf7d701f75d8b86c",
  • "object": "international_education_verification",
  • "uri": "/v1/international_education_verifications/41007cffefb435cf7d701f75d8b86c",
  • "status": "complete",
  • "result": "clear",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 603216,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "records": [
    ]
}

International Employment Verification

Verification of previous employment history may include employer’s name, dates of employment, position/title, reason for leaving, eligibility for rehire, and comments. Reasonable attempts will be made to verify available government agencies and employment databases. Email verification, and phone verification may be used in countries where the records of former employers are not available in searchable form, and where contacting the supervisor or manager is common practice. Refer to International Screenings for more details.

Retrieve an existing International Employment Verification

Returns an existing International Employment Verification with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the International Employment Verification to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "41007cffefb435cf7d701f75d8b86f",
  • "object": "international_employment_verification",
  • "uri": "/v1/international_employment_verifications/41007cffefb435cf7d701f75d8b86f",
  • "status": "complete",
  • "result": "clear",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 603216,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "records": [
    ]
}

Retrieve an existing International Global Watchlist Search

Returns an existing International Global Watchlist Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the International Global Watchlist Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "41007cffefb435cf7d701f75d8b87a",
  • "object": "international_global_watchlist_search",
  • "uri": "/v1/international_global_watchlist_searches/41007cffefb435cf7d701f75d8b87a",
  • "status": "complete",
  • "result": "clear",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "country": "FR",
}

International Identity Document Validation

Verifies that the candidate’s passport, national ID or driver’s license is authentic and validly in circulation. This check provides a multi-level validation process by inspecting document data and positioning for authenticity, scanning the Machine Readable Zone (if available), and cross-checking the information provided against government databases to discover if the document is stolen, lost, expired or invalid. Refer to International Screenings for more details.

Retrieve an existing International Identity Document Validation

Returns an existing International Identity Document Validation with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the International Identity Document Validation to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "41007cffefb435cf7d701f75d8b87b",
  • "object": "international_identity_document_validation",
  • "uri": "/v1/international_identity_document_validations/41007cffefb435cf7d701f75d8b87b",
  • "status": "complete",
  • "result": "clear",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
}

International Motor Vehicle Report

Checks the validity of a driver license and where available, may include a detailed history of the candidate’s driving violations or license conditions. Canada only at this time. Refer to International Screenings for more details.

Retrieve an existing International Motor Vehicle Report

Returns an existing International Motor Vehicle Report with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the International Motor Vehicle Report to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "41007cffefb435cf7d701f75d8b86d",
  • "object": "international_motor_vehicle_report",
  • "uri": "/v1/international_motor_vehicle_reports/41007cffefb435cf7d701f75d8b86d",
  • "status": "complete",
  • "result": "clear",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 90,
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "country": "CA",
  • "license_reports": [
    ]
}

Retrieve an existing FACIS Search

Returns an existing FACIS Search with the input ID.

Authorizations:
path Parameters
id
required
string

ID of the Facis Search to retrieve.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "status": "complete",
  • "result": "clear",
  • "cancellation_reason": "complete_now_customer_requested",
  • "cancellation_reason_description": "Customer requested Complete Now prior to screening completion",
  • "id": "e44aa283528e6fde7d542194",
  • "created_at": "2014-01-18T12:34:00Z",
  • "completed_at": "2014-01-18T12:35:30Z",
  • "turnaround_time": 345600,
  • "object": "facis_search",
  • "subtype": "1",
  • "records": [
    ]
}

Getting Started

Before you can start using Checkr's I9 verification endpoints please complete first adding Form I-9 to your account. A step by step guide can be found at Checkr Help Center

Forms I-9

The Forms I-9 resource provides all information about Forms I-9. It also allows to create a new Form I-9, retrieves details about ongoing I-9s (creating a CSV file) and also makes the PDF files for completed I-9s available.

List existing Form I-9s

Retrieves all I-9s for the authenticated Checkr account.

Authorizations:
query Parameters
order_by
string

Returns records listed by order_by parameter.

If neither is specified, records will be ordered by start_date.

Values include: "full_name" "start_date" "worksite_name" "open_task"
Example: order_by=full_name
order
string

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

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

Specifies the page number to retrieve.

per_page
integer
Default: 25

Indicates how many records each page should contain.

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/i9/forms_i9?order_by=start_date&order=desc&page=1&per_page=25 \ 
       -U YOUR_SECRET_API_KEY:

Response samples

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

Create a new Form I-9

Creates a new Form I-9 resource. This resource allow the creation of a single Form I-9 and also the creation of a bulk of Forms I-9 in one request.

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

Candidate resource Id.

email
required
string

Candidate email address.

worksite_id
required
string

Worksite resource Id.

workflow_type
required
string

Workflow type.

For additional insights into workflow types, please consider reviewing the Form I-9 definitions.

Values include: "remote_section_1_only" "employer_appointment" "employee_appointment"
start_date
required
string

Candidate start date.

authorized_representative_first_name
string

First name of authorized representative.

authorized_representative_last_name
string

Last name of authorized representative.

authorized_representative_email
string

Email address of authorized representative.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/i9/forms_i9 \
       -U YOUR_SECRET_API_KEY: \
       -H "Content-Type: application/json" \
       -d '{        
		"candidate_id": "3de7e278beb24d14a3785e2dd02cca49",
		"email": "john.doe@example.com",
		"start_date": "2023-04-29",
		"worksite_id": "8046067e32ad6b25a9078735",
		"workflow_type": "remote_section_1_only",
		"authorized_representative_first_name": "Lee",
		"authorized_representative_last_name": "Perry",
		"authorized_representative_email": "lee.perry@domain.com"	
	  }'

Response samples

Content type
application/json
{
  • "id": "1a16ef5f9c1f1df045e74bb4",
  • "object": "form_i9",
  • "uri": "v1/forms_i9/1a16ef5f9c1f1df045e74bb4",
  • "candidate_id": "3de7e278beb24d14a3785e2dd02cca49",
  • "order_progress": "section_1_incomplete",
  • "open_tasks": "complete_section_2",
  • "open_tasks_url": "",
  • "start_date": "2023-04-29",
  • "worksite_id": "8046067e32ad6b25a9078735",
  • "worksite_uri": "v1/i9/worksites/8046067e32ad6b25a9078735",
  • "workflow_type": "remote_section_1_only",
  • "authorized_representative_first_name": "Lee",
  • "authorized_representative_last_name": "Perry",
  • "authorized_representative_email": "lee.perry@domain.com",
  • "created_at": "2023-04-29T16:21:11Z"
}

Retrieve a Form I-9

Retrieves an existing Form I-9.

Authorizations:
path Parameters
id
required
string

ID of the Form I9

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/i9/forms_i9/1a16ef5f9c1f1df045e74bb4 \ 
       -H YOUR_SECRET_API_KEY:

Response samples

Content type
application/json
{
  • "id": "1a16ef5f9c1f1df045e74bb4",
  • "object": "form_i9",
  • "uri": "v1/forms_i9/1a16ef5f9c1f1df045e74bb4",
  • "candidate_id": "3de7e278beb24d14a3785e2dd02cca49",
  • "order_progress": "section_1_incomplete",
  • "open_tasks": "complete_section_2",
  • "open_tasks_url": "",
  • "start_date": "2023-04-29",
  • "worksite_id": "8046067e32ad6b25a9078735",
  • "worksite_uri": "v1/i9/worksites/8046067e32ad6b25a9078735",
  • "workflow_type": "remote_section_1_only",
  • "authorized_representative_first_name": "Lee",
  • "authorized_representative_last_name": "Perry",
  • "authorized_representative_email": "lee.perry@domain.com",
  • "created_at": "2023-04-29T16:21:11Z"
}

Retrieve Form I-9 PDF file

Retrieves a Form I-9 PDF file associated with the Form I-9 ID.

This endpoint returns a pre-signed S3 URL, valid for 5 minutes.

Authorizations:
path Parameters
id
required
string

ID of the Form I9

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/i9/forms_i9/1a16ef5f9c1f1df045e74bb4/pdf \ 
       -H YOUR_SECRET_API_KEY:

Response samples

Content type
text/plain
https://api.checkr.com/key_1?X-Amz-Credential=xyz%2F20231002%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20231002T182721Z&x-id=GetObject&X-Amz-Signature=00fa239977fddb97a5e66f899ac41c34726bb9fb34167c60aa97762a1360eda7

Worksites

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

List existing Worksites

Returns a list with all existing Worksites for the authenticated Checkr account.

Authorizations:
query Parameters
order_by
string

Returns records ordered by field.

If neither is specified, records will not be ordered.

Values include: "name" "street_line1" "street_line2" "city" "state" "zip_code"
Example: order_by=street_line1
order
string

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

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

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/i9/worksites?order_by=state&order=desc \ 
       -U YOUR_SECRET_API_KEY:

Response samples

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

Create new Worksite

Create new Worksites for the authenticated account.

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

Worksite name.

street_line1
required
string

Line one of Worksite address.

street_line2
string

Line two of Worksite address.

city
required
string

City of Worksite.

state
required
string

State of Worksite.

zip_code
required
string

ZIP Code of Worksite.

Responses

Request samples

$ curl -X POST https://api.checkr.com/v1/i9/worksites \
       -U YOUR_SECRET_API_KEY: \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -d '{        
               "name": "Head Office",
               "street_line1": "Some Rd",
               "street_line2": "Some Rd 2",
               "city": "San Francisco",
               "state": "California",
               "zip_code": "66554"
	}'

Response samples

Content type
application/json
{
  • "id": "8046067e32ad6b25a9078735",
  • "name": "Head Office",
  • "street_line1": "Some Rd",
  • "street_line2": "Some Rd 2",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "66554",
  • "everify_status": "not_determined"
}

Retrieve a Worksite

Returns a specified Worksite for the authenticated Checkr account.

Authorizations:
path Parameters
id
required
string

Worksite resource Id

Responses

Request samples

$ curl -X GET https://api.checkr.com/v1/i9/worksites/8046067e32ad6b25a9078735 \ 
       -U YOUR_SECRET_API_KEY:

Response samples

Content type
application/json
{
  • "id": "8046067e32ad6b25a9078735",
  • "name": "Head Office",
  • "street_line1": "Some Rd",
  • "street_line2": "Some Rd 2",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "66554",
  • "everify_status": "not_determined"
}

Update Worksite information

Update Worksite information

Authorizations:
path Parameters
id
required
string

Worksite resource Id

Request Body schema: application/json
name
string

Worksite name.

street_line1
string

Line one of Worksite address.

street_line2
string

Line two of Worksite address.

city
string

City of Worksite.

state
string

State of Worksite.

zip_code
string

ZIP Code of Worksite.

everify_status
string

Worksite E-Verify Status.

Values include: "active" "inactive"

Responses

Request samples

$ curl -X PUT https://api.checkr.com/v1/i9/worksites/79265751d363a140106fec15 \ 
    -U YOUR_SECRET_API_KEY: \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{        
            "name": "Updated Worksite",
            "street_line1": "Some Rd first",
            "street_line2": "Some Rd second",
            "city": "San Francisco",
            "state": "California",
            "zip_code": "66554",
            "everify_status": "inactive"
	}'

Response samples

Content type
application/json
{
  • "id": "79265751d363a140106fec15",
  • "name": "Updated Worksite",
  • "street_line1": "Some Rd first",
  • "street_line2": "Some Rd second",
  • "city": "San Francisco",
  • "state": "California",
  • "zip_code": "66554",
  • "everify_status": "inactive"
}

Delete a Worksite

Deletes specified Worksite. If there are at least one Form I-9 associated with a Worksite, this Worksite cannot be deleted.

Authorizations:
path Parameters
id
required
string

Worksite resource Id

Responses

Request samples

$ curl -X DELETE https://api.checkr.com/v1/i9/worksites/8046067e32ad6b25a9078735  \
       -U YOUR_SECRET_API_KEY:

Response samples

Content type
application/json
null