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.

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. Upload the candidate's consent PDF first, then include the returned document id in the required consent_document_ids field on that request.

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.

curl -X POST https://api.checkr.com/v1/reports \
  -u YOUR_API_KEY: \
  -d package=dunder_mifflin_executive \
  -d candidate_id=551564b7865af96a28b13f36 \
  -d consent_document_ids[]=b73f89e14b393979857806f9

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

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.)
• This object includes your certification to Checkr that appropriate disclosures and authorization (such as consent) have been obtained from your candidate.

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

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.

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. For information on using the Checkr Dashboard to order a Continuous Check package on a candidate, see Continuous checks in the Checkr Help Center.

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

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

1. 1

   Customer submits API request to Checkr for a candidate MVR

2. 2

   Checkr fulfills MVR, submits webhook response to customer with screening results

3. 3

   Customer determines if candidate passes or does not pass MVR requirements

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

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

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

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

openssl genrsa -out private.pem -aes256 4096

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

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

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